suno-craft-lv

name	suno-craft-lv
level	1.1
updated	"2026-06-12T00:00:00.000Z"
description	Full Suno surface on KIE.ai (models V3_5 → V5_5) — songs with vocals, instrumentals/BGM, custom lyrics, extend (generated or uploaded audio), restyle/cover uploaded audio, add-vocals/add-instrumental, 2-track mashup, replace a section inside a track, album cover art, word-level timestamped lyrics, style boosting, reusable personas, WAV export, vocal/stem separation (2 or 12 stems), MIDI extraction, SFX/ambient sound generation, MP4 visualizer videos, and custom voice cloning. Use whenever the user wants to create/generate/edit a song, music, BGM, jingle, SFX, or soundtrack — Thai (สร้างเพลง, แต่งเพลง, ทำเพลง, ทำ BGM, เพลงประกอบ, ดนตรีประกอบ, ทำเสียงประกอบ, แยกเสียงร้อง) or English ("make a song", "generate music", "background music", "sound effects", "extract stems/MIDI"). Handles the full async pipeline — submit, poll, download — with a resumable submit + wait split. Uses the same ~/.kie_api_key as kie-craft-lv. For images/video on KIE use kie-craft-lv; for TTS/spoken voice use elevenlabs-craft-lv.

Suno Craft — music generation on KIE.ai

One skill for the entire Suno surface on KIE (all 47 doc pages mapped). Same auth (~/.kie_api_key), same state-file pattern (~/.kie/tasks/suno-<id>.json), same resumable submit/wait split as kie-craft-lv.

Capability map → command (scripts/suno.py)

ความสามารถ	Command	Mode
สร้างเพลง (เนื้อ auto หรือเนื้อเป๊ะ)	submit	async
ต่อเพลงที่ gen ไว้ / ต่อไฟล์ของเรา	extend / upload-extend	async
เปลี่ยนสไตล์ไฟล์เสียงเรา (คง melody)	cover	async
ใส่เสียงร้องให้ instrumental / ใส่ดนตรีให้เสียงร้อง	add-vocals / add-instrumental	async
รวม 2 เพลงเป็นหนึ่ง	mashup	async
แก้เฉพาะท่อน (6-60s)	replace-section	async
เนื้อเพลงอย่างเดียว	lyrics	async
เนื้อเพลง + timing รายคำ (karaoke/lip-sync)	timestamped-lyrics	sync
ขยาย style สั้นๆ เป็นคำบรรยายรวย	boost-style	sync (0.4 cr)
Persona เสียง/สไตล์ ใช้ซ้ำได้	persona	sync
ปกอัลบั้ม 2 แบบ	cover-art	async (once/task)
WAV master	wav	async
แยก stems (2 หรือ 12 ชิ้น)	stems	async (10/50 cr)
โน้ต MIDI จาก stems	midi	async
SFX / ambient / loop (BPM+key control)	sounds	async
MP4 visualizer	video	async
โคลนเสียงตัวเอง (4 ขั้น มีอัดเสียงยืนยัน)	voice-validate → voice-phrase → voice-create → voice-check	interactive

Cost & LV tier gate

Every task records a balance diff in its state file (credits_spent) — but ⚠️ the KIE account is shared with ZenityX Studio production traffic, so the balance moves constantly and per-task deltas are unreliable (validated 2026-06-12: balance shifted −424 cr between idle checks). For exact pricing check https://kie.ai/billing in a browser. 1 credit = $0.005.

Tier	What	Cost	Rule
LV1 — cheap	Music generation (any model, simple or custom — produces 2 tracks per run), lyrics-only, WAV conversion, separate_vocal stems (10 cr ≈ $0.05, documented)	cents-level per run	submit freely
LV2 — mid	split_stem 12-stem separation (50 cr ≈ $0.25), MP4 visualizer video, cover/extend batches (>3 runs in one go)	$0.25–1	confirm the prompt/plan looks right before submit
LV3 — premium	Bulk generation (≥10 runs, e.g. "ทำเพลงให้ครบทุก muse"), anything projected >$1	$1+	explicit user opt-in first — echo back the projected cost

Music generation itself is cheap; the gate exists mostly to stop runaway batches. Never silently loop generation over a list without telling the user the total run count first.

Model router

Job	Model	Why
Default — any song/BGM	V5_5	newest, best quality (script default since 2026-06-15); supports personas
Alternative if V5_5 feels off	V5	strong musicality, fast, 8-min cap; also supports personas
Long structured songs (verse/chorus control)	V4_5PLUS or V4_5	strong prompt adherence, 8-min cap
Quick cheap drafts	V4_5ALL	"smart and fast"
Legacy compatibility (extend old V4 tracks)	V4	extend MUST match source model

Hard limits per model (custom mode): prompt 3,000 chars (V3_5/V4) or 5,000 (V4_5+); style 200 (V3_5/V4) or 1,000 (V4_5+); title 80.

The customMode decision — read before every submit

This is the #1 source of Suno API confusion. Two modes, different semantics:

	--custom off (simple)	--custom on
You provide	one prompt ≤500 chars describing the song	--style + --title (+ prompt = exact lyrics when vocals on)
Lyrics	auto-written from the concept (not literal)	sung verbatim from your prompt
Use when	"ทำเพลง lo-fi ชิลๆ ฟังตอนทำงาน"	user wrote/approved lyrics, or needs exact style+title control

Instrumental + custom → --style + --title required, prompt optional. Vocals + custom → --style + --title + prompt (the lyrics) all required.

Writing Thai lyrics? Generate them first (lyrics subcommand, or write them yourself — often better for Thai), let Trin approve, then submit custom mode with the approved text.

Workflow — resumable submit + wait

Generation takes 1–4 minutes. Always two steps (same reason as kie-craft-lv: Bash timeout kills blocking processes; state file makes wait resumable with zero credits lost):

cd ~/.claude/skills/suno-craft-lv/scripts

# Step 1 — submit (< 5 s, prints taskId). Model defaults to V5_5; pass --model to override.
python3 suno.py submit "dreamy Thai city-pop about Bangkok rain at night"

# Step 2 — wait (run with a LONG Bash timeout, e.g. 450000 ms; exit 3 = rerun to resume)
python3 suno.py wait <taskId> --output-dir ./suno-output

Each music run returns 2 track variants (both downloaded as MP3 + cover art). Pick the better one with Trin.

More examples:

# Custom mode — exact lyrics, style, and title (vocals)
python3 suno.py submit "$(cat lyrics.txt)" --custom \
  --style "Thai indie pop, female vocal, warm acoustic, 90 BPM" \
  --title "ฝนกรุงเทพ" --vocal-gender f          # uses V5_5 by default

# Instrumental BGM with style control
python3 suno.py submit --custom --instrumental \
  --style "lo-fi hip hop, vinyl crackle, soft piano, study beats" \
  --title "Focus Loop 01"

# Lyrics only (no audio, ≤200 char prompt)
python3 suno.py lyrics "อกหักแต่ยังยิ้มได้ แนว pop punk ภาษาไทย"

# Extend a generated track from the 60-second mark (model MUST match source — override the V5_5 default if the source was V5/V4!)
python3 suno.py extend <audioId> --model V5 --continue-at 60 \
  --prompt "build to an epic final chorus, then fade out"

# Cover: restyle an uploaded audio, keep the melody (local file auto-uploads)
python3 suno.py cover ./demo.mp3 --custom --style "orchestral cinematic epic" \
  --title "Demo (Orchestral)" --instrumental

# Post-processing on a finished track
python3 suno.py wav <taskId> <audioId>                      # studio-grade WAV
python3 suno.py stems <taskId> <audioId>                    # vocals+instrumental (10 cr)
python3 suno.py stems <taskId> <audioId> --mode split_stem  # 12 stems (50 cr — LV2)
python3 suno.py video <taskId> <audioId> --author "MUSE" --domain "zenityx.com"

# Each of these returns its own taskId → wait on it the same way
python3 suno.py wait <newTaskId>

status <taskId> = one quick poll. fetch <taskId> = download something that already finished. credits = current balance.

Gotchas (hard-earned, keep updated)

1. callBackUrl is mandatory on every submit endpoint even though we poll. The script auto-fills a placeholder; final status then comes back CALLBACK_EXCEPTION, which the script correctly treats as SUCCESS (results stay fetchable via record-info).
2. Result URLs expire in ~14 days — the script downloads immediately, as correctness not convenience.
3. Extend must use the source track's model version. Extending a V4 track with V5 fails.
4. 2 tracks per generation run — cost covers both; always present both options.
5. Simple-mode prompt cap is 500 chars. Longer prompts need --custom (3k–5k cap).
6. Thai lyrics: Suno sings Thai. Tone-accuracy is decent on V5+ but review the first run before batch-producing.
7. Sensitive-word filter: SENSITIVE_WORD_ERROR is terminal — rephrase, don't retry verbatim. Artist names / copyrighted lyrics in prompts can trigger it.
8. MUSE Diary caption rule applies: never mention Suno/KIE in any public-facing caption (Brand Rule #12) — disclosure stays generic "AI generated".
9. credits_spent in state files is unreliable — the KIE account is shared with ZenityX Studio production users, so the balance moves on its own. Don't alarm Trin about "expensive runs" based on it.
10. "Generate Music Cover" = album ART images, not a cover song. Audio covers = cover (uploaded file) — cover-art makes 2 images, once per task only.
11. MIDI input is a stems taskId, not a music taskId — run stems first. Output is structured notes JSON (no .mid file URL); convert with mido if a DAW file is needed.
12. boost-style successFlag returns the Chinese string "成功" (docs claim int) — check result != null instead. Cost measured: 0.4 credits.
13. add-vocals / add-instrumental support only V4_5PLUS/V5/V5_5 (no V4).
14. Voice cloning is human-in-the-loop: the flow stops at WAIT_VALIDATING until Trin records himself reading the verification phrase — never pretend to complete it autonomously.

Division of labour with sibling skills

• suno-craft-lv (this) → music: songs, BGM, stems, WAV, music video
• kie-craft-lv → images + video gen on KIE (Nano Banana, Veo, Kling, Seedance…)
• elevenlabs-craft-lv → TTS / voice clone / SFX (spoken word, not music)
• wavespeed-infinitetalk → lip-sync a face to audio (feed it a Suno vocal track!)

Pipeline idea that works: Suno song → stems to isolate vocal → InfiniteTalk lip-sync a MUSE portrait singing it.

References

• references/api.md — core endpoint specs (generate, record-info, extend, cover, lyrics, WAV, stems, video) with exact parameter tables
• references/advanced.md — extended endpoint specs (upload-extend, add-vocals/instrumental, mashup, replace-section, cover-art, timestamped-lyrics, boost-style, persona, MIDI, sounds, voice cloning) + pipeline recipes

Self-improvement protocol (lean)

After any session where this skill hit an API surprise (new model version, changed limit, new endpoint, wrong cost estimate): update the relevant section + add a CHANGELOG line. Measured costs from credits_spent in state files are ground truth — promote them into the LV gate table.

CHANGELOG

• 1.2 (2026-06-15) — Default model → V5_5 (was V5) across all generation subcommands: submit, extend, cover, upload-extend, mashup, sounds (default), add-vocals/add-instrumental (were V4_5PLUS). Per Trin's request — V5_5 is newest/highest quality. Model router + examples updated; pass --model to override (e.g. extend must still match the source track's model). Background: validated via real-signal analysis that JVKE "her" is 143.6 BPM / B major / airy-verse→bass-drop-chorus, and that matching the reference artist's language (English) is what made it land — see user memory feedback-song-lyrics-not-poetry.md.

• 1.1 (2026-06-12) — Full-surface coverage: explored ALL remaining doc pages (47/47 mapped — 32 read in full, 13 callback pages intentionally summarized, 2 dead slug guesses corrected). Added 13 new commands: upload-extend, add-vocals, add-instrumental, mashup, replace-section, cover-art, timestamped-lyrics, boost-style, persona, midi, sounds, voice-* (4-step cloning flow). Live-validated boost-style (0.4 cr, sync, successFlag="成功" quirk). Key corrections: cover-suno = album ART not audio cover; MIDI consumes stems taskId; numeric successFlag on cover/midi endpoints; sounds poll endpoint undocumented (raw-JSON fallback in place).

• 1.0 (2026-06-12) — Initial build from KIE Suno docs (docs.kie.ai/suno-api — 47 EN pages total per sitemap; 13 read in full, 9 summarized in advanced.md, callbacks pages intentionally skipped since we poll). Live-validated: submit (simple/instrumental/V5) + record-info polling + 2-track MP3/cover download (status flow PENDING → TEXT_SUCCESS → FIRST_SUCCESS → SUCCESS). All 5 polling paths doc-verified. Discovered: (a) callBackUrl mandatory on all submit endpoints → placeholder pattern, (b) shared KIE account makes credit-delta measurement unreliable, (c) V5 simple-mode returns rich auto-written style tags in tags field — recyclable into future custom-mode styles, (d) wav/vocal/mp4 detail endpoints use successFlag while music/lyrics use status — script checks both, (e) unexplored sections exist: MIDI gen, Sounds gen, Suno Voice suite (see advanced.md).