kie_audio — Suno music generation via Kie.ai#

Generate music and audio via Kie.ai's Suno gateway. Handles Suno's multi-stage state machine ( PENDING → TEXT_SUCCESS → FIRST_SUCCESS → SUCCESS) and downloads all generated tracks (Suno often returns variations) when done.

When to use#

• User wants a background track, intro, outro, instrumental bed.
• User wants a song with vocals from a lyric or story prompt.
• User explicitly says Suno, V5, V4.5+, etc.
• User wants to extend an existing audio clip.

Models#

--modelNotesV3_5Oldest, cheapestV4``V4_5``V4_5PLUS``V5``V5_5 (default)Latest, highest quality

How to invoke#

Use the exec tool. {baseDir} = this skill's folder.

Instrumental lofi loop#

text

exec:
  command: python3 {baseDir}/scripts/generate.py --model V5_5 --instrumental --prompt "lofi hip hop, rainy afternoon, mellow piano, soft vinyl crackle, 30 seconds" --out ./out
  yieldMs: 1000

Full song with vocals (custom mode)#

text

exec:
  command: python3 {baseDir}/scripts/generate.py --model V5 --custom-mode --prompt "upbeat indie pop, chorus about summer road trips, male vocal" --out ./out```

### Extend existing audio

exec: command: python3 {baseDir}/scripts/generate.py --extend https://example.com/original.mp3 --prompt "continue with a building bridge then a final chorus" --model V5_5 --out ./out```

Full CLI reference#

text

python3 {baseDir}/scripts/generate.py \
    --prompt "..." \
    [--model V3_5|V4|V4_5|V4_5PLUS|V5|V5_5] \
    [--instrumental] [--custom-mode] \
    [--extend AUDIO_URL] \
    [--out ./out] \
    [--callback-url URL] [--callback-port 8787] [--no-wait] [--timeout 900]

Output#

The script prints JSON to stdout:

json

{
  "taskId": "abc123...",
  "tracks": [
    {"audio": "./out/abc123_1.mp3", "duration": 125, "cover": "./out/abc123_1_cover.jpg"},
    {"audio": "./out/abc123_2.mp3", "duration": 130, "cover": "./out/abc123_2_cover.jpg"}
  ]
}

Important#

• Suno usually generates multiple tracks per request — the script downloads all of them plus their cover images.
• State transitions are logged to stderr so you can see progress during polling.
• Failure codes to watch: 400 (possible copyright), 413 (audio conflict), 501 (generation failed), 531 (server error — Kie auto-refunds credits).
• All tracks expire at 14 days, download immediately.

Environment#

• KIE_API_KEY — required. https://kie.ai/api-key
• KIE_WEBHOOK_HMAC_KEY — only when using --callback-url

Both are auto-loaded from ~/.openclaw/openclaw.json → globalEnv by the bundled script. No need to pass env: into exec.