Skip to content

suno_api.md

Latest commit

 

History

History
79 lines (57 loc) · 2.41 KB

suno_api.md

File metadata and controls

79 lines (57 loc) · 2.41 KB
Raw

Suno API

Notes for the scripts/music/suno.py adapter. Update this doc (and the adapter) when Suno ships breaking changes.

Auth

Bearer token. Key lives in SUNO_API_KEY (env or .env). Obtain from Suno account settings. The adapter also honors SUNO_BASE_URL to support proxied deployments; default is https://api.suno.ai.

Endpoints the adapter uses

  • POST /api/generate/v2 — kick off a generation. Body keys used by the adapter:

    • prompt — the song description (natural-language, not lyrics).
    • tags — comma-separated style tags (optional).
    • make_instrumental — boolean.
    • wait_audio — false so we can poll ourselves. Returns a list of job descriptors; each has an id (a.k.a. song_id).

  • GET /api/feed?ids=<job_id> — poll. Returns a list of items. Look for audio_url populated (success) or status == "error" (failure).

Polling

Default interval 4 s, timeout 5 min. Adjust in scripts/music/suno.py:

_POLL_INTERVAL_SECONDS = 4.0
_POLL_TIMEOUT_SECONDS = 300.0

Songs typically come back in 60–90 s; longer tracks can push to 3 min.

Request shape

The adapter sends:

{
  "prompt": "<user prompt>",
  "tags": "<style>",          // optional
  "make_instrumental": true,
  "wait_audio": false
}

If you need lyrics: set make_instrumental: false and put the lyrics into the prompt, OR use Suno's Custom Mode (requires title + lyrics fields — not implemented here yet; extend the adapter if needed).

Downloading

audio_url points to an MP3. The adapter streams it to build/music/suno_<job_id>_<take_idx>.mp3.

Common failures

  • 401 Unauthorized — SUNO_API_KEY missing or wrong.
  • 429 Too Many Requests — rate limited. Back off and retry.
  • status: error in feed — surface error_message to the user; no retry loop (user decides).
  • Timeout — increase _POLL_TIMEOUT_SECONDS, or accept that the job will finish later and abort this take.

Extending to Custom Mode

If a user wants to specify lyrics/title/structure, extend SunoProvider:

  1. Add fields to SongSpec (title, lyrics).
  2. Switch to POST /api/generate (v1 custom) or send the extra fields in v2 once Suno supports them.
  3. Document the new fields in song_builder_agent.md so the sub-agent knows to ask for them.

Keep the existing default path (prompt + tags + instrumental) working — most promo use cases don't need lyrics.