feat(lacuna_music): add Lacuna Music plugin v0.1.0

[LouisTsang-jk]

Plugin Submission

Plugin information

• Author: lacuna (JOYLINK LTD)
• Plugin name: lacuna_music (Lacuna Music)
• Version: 0.1.0
• Source repository: https://github.com/JOYLINK-LTD/lacuna-toolkit (plugin source under dify/lacuna)
• Contact: support@lacuna.fm

Submission type

• New plugin
• Version update

What changed

New tool plugin for the Lacuna Music API. It generates original music from a text style
description — background beds and soundtrack loops for video, podcast, game and ad workflows, and
full vocal tracks when lyrics are supplied — and returns hosted MP3 URLs for the next node.

Three tools:

• generate_music — submits a generation and polls until the audio is ready (blocking).
• create_generation — queues the same request and returns the task id immediately.
• get_generation — reads a task's status and, once ready, its audio URLs. Free, no credits.

Credentials: a single secret-input API key, validated on save by a probe against a task id that
cannot exist. Lacuna checks the key, its scopes and the account plan before looking the task up, so a
404 proves the credential works — nothing is generated and no credits move.

Risk level

• Low risk
• Medium risk
• High risk

Medium rather than low because the plugin sends user-authored content (style description, lyrics,
title) to a third-party service and performs a write action there by queueing a generation. It calls
one fixed, documented HTTPS host and nothing else.

Required checks

• I have read and followed the Marketplace submission requirements.
• I have read and comply with the Plugin Developer Agreement.
• I tested this plugin on Dify Community Edition and Dify Cloud, or documented any limitation below.
• The package contains only files needed at runtime.
• The package does not contain secrets, local credentials, .env files, .git directories, virtual environments, caches, logs, or IDE files.
• The package does not contain executables or bundled binaries, or I explained why they are required below.
• The plugin README includes setup steps, usage instructions, required APIs or credentials, connection requirements, and the source repository link.
• The plugin includes PRIVACY.md or a hosted privacy policy, and manifest.yaml references it.
• All user-facing text is primarily in English, with any localized README files following the i18n guidance.

Security and privacy notes

No command execution, code execution, SQL, SSH/SFTP, browser automation, filesystem access or
arbitrary URL fetching. The plugin reaches exactly one host, www.lacuna.fm, declared in
manifest.yaml under network.domains. It does not read environment variables or files, stores
nothing locally, and does not download the generated audio — it passes the URLs through.

No health, financial, biometric, children's, location or authentication data is processed. The only
credential is the Lacuna API key, held in Dify's secret-input field; it is never logged and never
included in an error message.

On the prohibited_financial_activity warning: the validator flags the word "credits" in the
README and in two error messages. Those refer to Lacuna's own prepaid account balance, which the
Lacuna API meters and refunds server-side. The plugin performs no payment, transfer or token
movement of any kind, presents no checkout, and handles no payment instrument — it only reports the
credits_used and credits_refunded numbers the API returns so a workflow can log them.

Local validation

$ dify-plugin plugin package ./lacuna -o lacuna_music-0.1.0.difypkg
INFO plugin packaged successfully

$ python validate-difypkg.py lacuna_music-0.1.0.difypkg

| Check                           | Type     | Status | Findings     |
|---------------------------------|----------|--------|--------------|
| package_contents                | blocking | PASS   | No findings. |
| package_secrets                 | blocking | PASS   | No findings. |
| package_binaries                | blocking | PASS   | No findings. |
| manifest_metadata               | blocking | PASS   | No findings. |
| readme_metadata                 | blocking | PASS   | No findings. |
| package_dependencies            | blocking | PASS   | No findings. |
| python_compile                  | blocking | PASS   | No findings. |
| python_safety                   | warning  | PASS   | No findings. |
| prohibited_financial_activity   | warning  | PASS   | see note above |
| access_domains                  | warning  | PASS   | www.lacuna.fm (declared) |
| dependency_vulnerabilities      | warning  | PASS   | 2 pinned, 0 unpinned |

Tool logic is covered by unit checks on the request builder (required fields, the instrumental /
lyrics rule, and dropping the aether-only controls when another model is selected) plus a live check
that an invalid key surfaces the API's 401 message.

Reviewer notes

Dependencies are pinned exactly (dify-plugin==0.10.1, requests==2.34.2) so the vulnerability
check has something to look up. No binaries, no bundled assets beyond a 1 KB SVG icon.

Known limitation: a generation takes a few minutes, so generate_music blocks while polling and the
plugin raises MAX_REQUEST_TIMEOUT to 600s. Workflows that should not block that long can use
create_generation plus get_generation, or subscribe to Lacuna's job.completed webhook.

[crazywoola]

✅ LGTM

Decision: Approve

Local Check Results

Check	Status	Detail	Required action
PR content language	✅ Pass	PR title/body CJK ratio=0.0% (zh=0, en=3507, ignored_zh=0, allowed_zh<=0)	None.
Project structure	✅ Pass	All expected files present: manifest.yaml, README.md, PRIVACY.md. _assets/: yes.	None.
Manifest author	✅ Pass	author is valid.	None.
Icon validation	✅ Pass	icon exists: _assets/icon.svg	None.
Version check	✅ Pass	version 0.1.0 is available.	None.
README language	✅ Pass	README.md CJK ratio=0.0% (zh=0, en=2666, allowed_zh<=0)	None.
PRIVACY.md	✅ Pass	PRIVACY.md exists and is non-empty.	None.
Dependency install	✅ Pass	requirements installed successfully.	None.
dify_plugin version	✅ Pass	dify_plugin version 0.10.1 satisfies >= 0.9.0.	None.
Install test	✅ Pass	plugin install test passed.	None.
Packaging test	✅ Pass	packaging check passed.	None.