Add illustrated step-by-step tutorials for Suno

.difyignore

@@ -9,3 +9,4 @@ __pycache__/
 *.difypkg
 tests/
 pyproject.toml
+docs/

README.md

@@ -1,80 +1,121 @@
-# Suno for Dify
+# Suno for Dify: step-by-step guide
 
-Use the Ace Data Cloud Suno APIs in Dify workflows. Maintained by Ace Data Cloud. The plugin is free; API calls require your own authorized account and use the current service pricing.
+Generate instrumental music and retrieve the completed audio. This guide takes you from your first API key to the result in a Dify Workflow. Screenshots use Dify CE 1.17.1 in English; later versions may move the same controls.
 
-## Setup
+[Read in Simplified Chinese](https://github.com/AceDataCloud/SunoDify/blob/main/readme/README_zh_Hans.md) · [API and pricing](https://platform.acedata.cloud/models)
 
-1. Activate the service at [Ace Data Cloud](https://platform.acedata.cloud/console/applications), check [current pricing](https://platform.acedata.cloud/models), and create an API token with the required service access.
-2. Install from [Dify Marketplace](https://marketplace.dify.ai/plugin/acedatacloud/suno). This version is published and was installed through the official Marketplace flow in Dify CE 1.17.1 with signature verification enabled. Installation is optional; this does not mean Dify preinstalls the plugin.
-3. In Dify's **Plugins / Tools** page, authorize this provider with **Bearer Token** (`acedata_bearer_token`). Do not include credentials in prompts or exported workflows. Credential validation never generates media. Authorization performs a read-only task query.
+## 1. Install the correct plugin
 
-## Tools
+Open [Suno by acedatacloud](https://marketplace.dify.ai/plugin/acedatacloud/suno) in Dify Marketplace. Check the author is **acedatacloud**, choose **Install**, and select your Dify workspace. In your Dify workspace, open **Integrations → Tools → Tool Plugin** and select **Suno**. Its card should say **From Marketplace**.
 
-| Tool | API |
+If your Dify server cannot open Marketplace, ask its administrator to enable outbound access and plugin installation. The plugin needs HTTPS to `api.acedata.cloud`.
+
+![Installed plugin in Dify](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/01-installed.png)
+
+## 2. Get an API key with the correct access
+
+1. Sign in at [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications).
+2. Open **General application**. Its API key can access multiple services your account is entitled to use. A service-specific key is limited to that service. For this tutorial, check **Suno** access and current pricing/balance before generating.
+3. To reuse the selected key, click the copy icon marked **1** below. To create a separate Dify key, click **Manage Keys** marked **2**, then **Create**.
+
+![Copy an existing API key or open Manage Keys](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/get-api-key-en.png)
+
+4. Give the new key a name, such as `Dify tutorial`. Set expiration and usage/API restrictions only as needed, then click **Create**. Return to the key list or application card and copy the key. If **Allowed APIs** is enabled, include both the generation and task-query APIs used here: `/suno/audios`, `/suno/tasks`.
+
+![Create an optional separate key](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/create-api-key-en.png)
+
+Copy only the token string. Do not add `Bearer `, quotation marks, or the screenshot's redacted characters. A platform management token (for example, a `platform-...` token) is not the generation API key this plugin expects. Confirm service access and a sufficient balance before the first run.
+
+## 3. Authorize Suno in Dify
+
+1. Open **Integrations → Tools → Tool Plugin → Suno**.
+2. Click **API Key Authorization Configuration**. If an authorization already exists, click **1 Authorization** first, then the configuration button.
+3. Enter an **Authorization Name**, such as `Ace Data Cloud`, and paste the copied token into **Ace Data Cloud Bearer Token**.
+4. Choose who may use the credential and click **Save**. Never put a key in a prompt or workflow export.
+
+![Dify tool authorization dialog](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/02-authorize.png)
+
+## 4. Build your first Workflow
+
+Open **Studio → Create → Create from Blank → Workflow**, name it, and create this path by dragging from each node's right connector to the next node:
+
+**Start → Suno Generate Audios → Suno Retrieve Task → Output**.
+
+Use the **+** button to add a **Tool**, select this plugin, and choose the exact action above. Rename the generation node **Suno** and the query node **Retrieve completed task** to match the screenshots. Leave Start inputs empty for this fixed first example. Keep **Retry on Failure** off on the generation node.
+
+![Workflow connections](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/03-workflow.png)
+
+Select **Suno Generate Audios** and set these fields. Leave unmentioned optional fields empty.
+
+| Dify field | First-run value |
 |---|---|
-| `suno_generate_audios` | `POST /suno/audios` |
-| `suno_generate_lyrics` | `POST /suno/lyrics` |
-| `suno_upload_reference_audio` | `POST /suno/upload` |
-| `suno_get_mp4` | `POST /suno/mp4` |
-| `suno_get_mp3` | `POST /suno/mp3` |
-| `suno_get_wav` | `POST /suno/wav` |
-| `suno_get_midi` | `POST /suno/midi` |
-| `suno_get_timing` | `POST /suno/timing` |
-| `suno_create_vox_audio` | `POST /suno/vox` |
-| `suno_enhance_style` | `POST /suno/style` |
-| `suno_mashup_lyrics` | `POST /suno/mashup-lyrics` |
-| `suno_create_voice` | `POST /suno/voices` |
-| `suno_create_persona` | `POST /suno/persona` |
-| `suno_list_personas` | `GET /suno/persona` |
-| `suno_delete_persona` | `DELETE /suno/persona` |
-| `suno_custom_models` | `POST /suno/custom-models` |
-| `suno_projects` | `POST /suno/projects` |
-| `suno_task_retrieve` | `POST /suno/tasks` |
-| `suno_tasks_retrieve_batch` | `POST /suno/tasks` |
+| Model (`model`) | `chirp-v6` |
+| Instrumental (`instrumental`) | `true` |
+| Duration (`duration`) | `10` |
 
-See [CAPABILITIES.md](CAPABILITIES.md) for the current MCP comparison and parameter equivalents. All exposed inputs follow the current published API; model combinations and availability still depend on the service.
+**Prompt** (`prompt`):
 
-## Run a workflow
+```text
+A short gentle instrumental piano melody for a sunrise, no vocals.
+```
 
-For generation, use **Start → generation tool → task retrieval → Output**. Fill the prompt/text and model, and enter arrays/objects as JSON. Optional values can be left empty. The example requests in [tests/contract-examples.json](https://github.com/AceDataCloud/SunoDify/blob/main/tests/contract-examples.json) show valid shapes; example.org URLs are placeholders that must be replaced with your own accessible media.
+Turn **Instrumental** on for this first run. Duration is a target, not a guaranteed track length. Custom vocal music needs lyrics or a lyric prompt. A playable preview while running is not a final result.
 
-A submission can return `status=pending` with `task_id`. Save that ID, then use the retrieval tool with `wait_seconds=0` to read once, or 1–240 for a bounded wait. If still pending, query the same task again. Disable automatic retries on generation nodes. No paid request is automatically retried and no substitute model is selected.
+![Fill the generation or search parameters](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/03-configure.png)
 
-`status`, `success`, `task_id`, `trace_id`, `media_urls`, `data`, and `result` are available as Dify variables. Only a terminal successful result has `success=true`; intermediate previews remain pending. Batch queries preserve the state of each item. Terminal task failures raise a tool error. Synchronous search, text and management results are returned directly in `data`/`result`. The plugin does not execute model-generated tools.
+## 5. Wait for the same task and map the result
 
-Includes music actions, lyrics, media formats, voices, personas, custom models and projects. Voice/custom-model operations require authorized source recordings. Model creation has its own API price; review current pricing before use.
+Select **Suno Retrieve Task**. In **Task ID**, click the variable picker (or type `/`) and choose **Suno → task_id**. It must be the output variable from the generation node, not its name typed as plain text. Set **Wait up to seconds** to `240`; leave Trace ID empty for this example.
 
-Task/query calls retry transport failures at most twice. Generation has one attempt and a 10-second connect / 60-second read timeout. After a timeout, inspect [request history](https://platform.acedata.cloud/console/usages) before resubmitting; the accepted task may still be running. Delete/archive operations require `confirm=true`.
+![Task ID variable binding](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/04-task-id.png)
 
-## Branding and privacy
+Select **Output**, click **+** to add output fields, and choose the variables below from **Retrieve completed task**:
 
-The plugin uses the exact existing system asset recorded in [branding provenance](https://github.com/AceDataCloud/SunoDify/blob/main/tests/branding-source.json), for both light and dark icons. No logo was generated or redrawn. Asset SHA256: `d2ccb1c0039519a68913ad447114f8f9ecca161ffc2105cd61c414e06f8747d9`.
+| Output name | Select from query node | Type |
+|---|---|---|
+| status | status | String |
+| success | success | Boolean |
+| task_id | task_id | String |
+| media_urls | media_urls | Array[String] |
+| result | result | Object |
 
-Requests go directly to `https://api.acedata.cloud`. The plugin passes reference URLs to that API and returns media links; it does not fetch arbitrary reference URLs. Dify may fetch/render output links under its own policies. Never submit media you lack permission to process. See [PRIVACY.md](PRIVACY.md).
+![Map the query outputs](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/05-output.png)
 
-API charges are recorded in Credits in your Ace Data Cloud account. Check the actual usage ledger; Dify execution counts are not a billing ledger. USD = Credits × your current package price / amount.
+Click **Test Run → Start Run**. Generation may finish before the bounded wait expires; otherwise `status=pending` is normal. **Do not rerun the whole workflow while it is pending**, because that submits a new generation. Copy its task ID and create a separate **Start → Suno Retrieve Task → Output** workflow with that ID and a wait of 0 or 240. Query the same ID until `status=succeeded` and `success=true`; then open the links in `media_urls`. A green Dify workflow alone is not proof that the service task finished.
 
-## Development and evidence
+## 6. Check the expected output
 
-Python 3.12 is required. Install `requirements.txt`, then run:
+A completed result has this shape (the URL below illustrates the field; use your own returned URL):
 
-```sh
-python -m pytest tests -q
-ruff check .
-ruff format --check .
-dify plugin package .
+```json
+{
+  "status": "succeeded",
+  "success": true,
+  "media_urls": [
+    "https://.../result.mp3"
+  ]
+}
 ```
 
-Source contracts, MCP mappings, brand provenance and offline cases are in `tests/`. Recorded real Dify results state their exact coverage; they do not establish all models/options or Dify Cloud/Marketplace installation. See [tests/README.md](https://github.com/AceDataCloud/SunoDify/blob/main/tests/README.md).
+![Actual completed Dify result](https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/06-result.png)
+
+Actual run example; your task ID and media URL will differ.
+
+## Troubleshooting
+
+| What you see | What to do |
+|---|---|
+| Authorization fails / 401 or 403 | Copy the full API token, remove `Bearer `, check service access, balance, expiration and Allowed APIs. |
+| Invalid parameter / 400 | Copy the exact example model, action, resolution and JSON shape. Do not combine unrelated action fields. |
+| `pending` or an empty media list | Query the same task ID again. Never regenerate just to poll. |
+| HTTP 429 | Wait, reduce concurrency and check service limits; do not enable automatic paid retries. |
+| Timeout / 5xx / failed task | Inspect the original task or request history before resubmitting. Contact support with task/trace ID, never your key. |
+| Media link will not load | Check the task is terminal and the returned link is accessible from the Dify server/browser. |
 
-- Source: https://github.com/AceDataCloud/SunoDify
-- Issues: https://github.com/AceDataCloud/SunoDify/issues
-- Contact: dev@acedata.cloud
-- License: MIT
-- [Simplified Chinese](readme/README_zh_Hans.md)
+[Download the ready-to-import workflow](https://github.com/AceDataCloud/SunoDify/raw/refs/heads/main/docs/quickstart.dify.yml). Import it in Studio, then configure your own key; the file contains no credentials.
 
-## Official Marketplace verification
+## Privacy, cost and support
 
-[Install from Dify Marketplace](https://marketplace.dify.ai/plugin/acedatacloud/suno). Version 0.0.1 was downloaded and installed through the official Marketplace flow on October 8, 2026, with signature verification enabled and no remote-debug process. The installed plugin then completed the recorded real Dify workflow. [Verification data](tests/marketplace-acceptance.json) and [original Dify screenshot](tests/evidence/marketplace-20261008.png) document the exact scope. This proves optional Marketplace availability, not default installation or featured placement.
+The free plugin sends your chosen inputs and token to `api.acedata.cloud`; API calls follow current service pricing. Keys stay in Dify credential storage. See [Privacy](https://github.com/AceDataCloud/SunoDify/blob/main/PRIVACY.md). Only submit content you have permission to process.
 
-The installed tool queried a previously generated, completed task and returned its final media. The generation itself was not repeated; earlier generation evidence remains separate.
+[Source](https://github.com/AceDataCloud/SunoDify) · [Report a problem](https://github.com/AceDataCloud/SunoDify/issues) · dev@acedata.cloud · [Advanced capabilities](https://github.com/AceDataCloud/SunoDify/blob/main/CAPABILITIES.md). Development and test evidence live in the source repository, separate from this first-run guide.

_assets/tutorial/key-screenshots-provenance.json

@@ -0,0 +1,25 @@
+{
+  "captured_at": "2026-10-08T17:15:13.782Z",
+  "source_url": "https://platform.acedata.cloud/console/applications",
+  "auth": "Existing authorized account, own identity",
+  "privacy": "Balance, application ID and complete/partial token are opaque-masked before screenshot capture. Dialog crops omit unrelated UI.",
+  "edits": "Crop + numbered callouts on live screenshot only; no UI data or success state fabricated.",
+  "capture_actions": "Read application page, open Manage Keys, open Create, fill example name, cancel; no credential created and no billable API call.",
+  "instructions": {
+    "1": "Copy the selected existing key. The screenshot redacts it. Paste only token in Dify, not the Bearer label.",
+    "2": "Manage Keys, then Create; use own key name and appropriate restrictions. Return to the list/application page to copy."
+  },
+  "files": [
+    {
+      "file": "create-api-key-en.png",
+      "sha256": "977c06780b36ca33f2fb3ba546e2594efe5895400e4cb58d842eb564c3bb09da",
+      "bytes": 25251
+    },
+    {
+      "file": "get-api-key-en.png",
+      "sha256": "b63787f2bd15af82fef9ab61c99e11c454355ac86e91f7f94559386b795069b7",
+      "bytes": 33708
+    }
+  ],
+  "published_screenshot_language": "English only in every locale, per explicit user instruction"
+}