--- name: suno-music description: SOTA full-song generation (melody + lyrics + vocals) via Suno API (sunoapi.org). Use when Dr. Wael wants a COMPLETE professional song with singing — superior to MiniMax Music / Lyria 3 for vocal songs. For instrumental-only or quick clips, MiniMax/Lyria may suffice. Verified live 2026-06-01 (1050 credits). ---

Suno Music Skill (SOTA vocal songs)

When to use Suno (vs alternatives)

• Full song with vocals + lyrics + melody → Suno (SOTA).
• Instrumental / background / quick clip → MiniMax music-2.6 or Lyria 3 Pro (cheaper, already in music_generate tool).
• Cover version → MiniMax music-cover.

Engine (verified live 2026-06-01)

• Provider: sunoapi.org (SUNO_API_BASE=https://api.sunoapi.org)
• Auth: SUNO_API_KEY in env.sh (Bearer)
• Credits check: GET /api/v1/generate/credit → returned 1050 ✅
• Generate: POST /api/v1/generate → returns taskId ✅
• Models: V3_5, V4, V4_5, V4_5PLUS, V5 (use newest = V5; V4_5PLUS fallback) — confirmed available on sunoapi.org 2026-06-21, balance 1026 credits
• Async: poll taskId (no callback server needed).

🔤 Arabic rule

Before any Arabic lyrics → run through CATT tashkeel (skills/arabic-tashkeel/) for correct pronunciation.

Usage

bash
Generate a full song (custom mode = you provide lyrics + style + title)
python3 skills/suno-music/suno.py generate \
  --lyrics "lyrics here" --style "arabic pop, warm, acoustic" --title "..." --model V4_5PLUS
Quick mode (Suno writes lyrics from a prompt)
python3 skills/suno-music/suno.py generate --prompt "happy children song about Eid" --model V4_5
Instrumental only
python3 skills/suno-music/suno.py generate --prompt "calm oud instrumental" --instrumental --model V4_5
Check credits
python3 skills/suno-music/suno.py credits

Output

• Downloads finished MP3(s) to /tmp/suno_<taskId>_N.mp3
• Suno returns 2 variations per request by default.
• Compress if >45MB before Telegram MEDIA (TOOLS.md rule).