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
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)
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
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:
{
"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-keyKIE_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.