Kie Audio Generator

Generate music and audio via Kie.ai's Suno gateway (V3.5 through V5.5). Use for background tracks, instrumental beds, full songs with vocals, or extending existing audio clips. Trigger on "suno", "generate music", "background track", "lofi beat", "song with vocals", "extend audio", "music via kie".

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

--model	Notes
V3_5	Oldest, cheapest
V4
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.