- name
- kie_audio
- description
- 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".
- metadata
- {"openclaw": {"emoji": "🎵", "requires": {"bins": ["python3"], "env": ["KIE_API_KEY"]}, "primaryEnv": "KIE_API_KEY"}}
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: 1000Full 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.