mcerqua/openvoiceui/suno-music

Suno Music

OpenVoiceUI (OVU) wraps the Suno API (sunoapi.org) behind two voice tags and /api/suno. It submits the job, saves the finished audio in generated_music/ with its metadata (title, lyrics, Suno ids) and adds it to the music player's Generated playlist.

• Requires `SUNO_API_KEY` in the OVU `.env`; without it every /api/suno call returns

{"action":"error","response":"SUNO_API_KEY not configured ..."}.

• Examples use http://localhost:5001; if you changed PORT, use that port.
• -H "X-Agent-Key: ${AGENT_API_KEY:-}" is needed only when the install requires login (Clerk +

CANVAS_REQUIRE_AUTH) and AGENT_API_KEY is set in .env; harmless otherwise.

• Everything is async: songs and jingles take about 45-90 s, sound effects about 20-60 s.

Rules

• Always go through OVU (the tags or /api/suno). Never call the Suno provider directly and

never use OpenClaw's built-in music tool: only OVU saves the file in generated_music/ with metadata and a shareable URL. Anything else is paid for and invisible to the user.

• Never write into `generated_music/` yourself, never invent a filename or URL.
• Every generation costs credits (approximate: song or jingle ~12, since Suno makes two clips

and OVU keeps the first; sound effect ~2.5; the live balance comes from the provider). Never fire the same request twice.

• Do not say it is done until you see the completion notice or status returns complete.
• No real artist or band names anywhere in a request; the provider rejects them. Describe the

sound (genre, era, instruments, mood, tempo).

• Never put `[` or `]` inside a tag. The tag ends at the first ]; the request is truncated

and the rest is spoken aloud.

Which method

Tag: [SUNO_GENERATE:...] (full song)

[SUNO_GENERATE:<description> | style:<style> | title:<title> | voice]

Options after the first | are optional. The browser submits it, shows a status banner and polls until the song is saved. On the user's next turn you get [SYSTEM: Suno just finished generating "<title>" ...]; if they want to hear it, reply with [MUSIC_PLAY:<title>]. The tag is removed from speech; say it will be ready in about a minute.

• Description mode (normal): Suno writes the lyrics and picks the title, so title: is

ignored and the filename follows Suno's title. Style plus description is cut to 500 chars.

• Vocals default to male and the tag cannot change that; use the API with "vocal_gender":"f".
• "No vocals" is only a hint; use the API with "instrumental":true when it must be instrumental.
• One tag per reply. The browser tracks one job at a time and drops an identical prompt

repeated within 60 s. For several songs, use the API.

• voice: sings the description as lyrics (lines separated by newlines or /) in the cloned

voice stored as voice_persona_id in the active profile (see Personas); without it, a default voice.

[SUNO_GENERATE:upbeat corporate background music, warm piano and soft strings, no vocals, 110 BPM]
[SUNO_GENERATE:fun country pop song about a roofer who never misses a deadline | style:country pop, upbeat]

Tag: [JINGLE_GENERATE:...] (10-15 s brand jingle)

[JINGLE_GENERATE:brand|style|gender|instrumental|repeat]

Presets (action=jingle_styles): rock, country, cinematic, gospel, lofi-hiphop, jazz, edm, bluegrass, synthwave, latin, reggae, gritty-blues, orchestral, punk, rnb. With no style from the user, leave it empty.

Users call this a jingle, logo jingle, audio or sonic logo, brand sting, stinger, bumper, station ID, podcast or channel intro, on-hold or IVR intro. Treat all of them as a jingle and ask only for the brand, a style (or "surprise me") and male, female or instrumental.

Clean the brand, keep the delivery. When users type how it should be sung (OOOOhhhPIN-VoIcE- UUUUUIIIIII, BEEEEM-DOUBLE-YOUUU), put the plain phonetic name in brand (OpenVoice U-I, B-M-W) and the delivery in up to three freetext style words: stretched vowels -> sustained operatic vocal; hyphenated letters -> punchy spelled-out chant; CAPS with !!! -> shouty stadium chant; lowercase with ... -> breathy intimate whisper. Anything that is not exactly a preset key is freetext, so a preset cannot be combined with extra words. If unsure, ask one short question before the paid generation.

[JINGLE_GENERATE:Acme Plumbing|country|m]
[JINGLE_GENERATE:OpenVoice U-I||f]
[JINGLE_GENERATE:Stark Industries|cinematic|m|true]

The server builds a short prompt (<brand> <brand> <style word> vocal logo jingle, [Intro, model V5) designed to stop early. To omit the style word entirely (bare), use the API.

Length is not guaranteed. Suno often overshoots. Over 20 s, the status reply says so; check duration_seconds via action=list_jingles and offer a retry rather than presenting a long clip as a finished jingle.

Sound effects: action=sfx

curl -s -X POST http://localhost:5001/api/suno \
  -H "Content-Type: application/json" -H "X-Agent-Key: ${AGENT_API_KEY:-}" \
  -d '{"action":"sfx","prompt":"retro 8-bit coin pickup blip","title":"coin pickup"}'

Fields: prompt (required, short and literal, max 500 chars), title, loop (true for a seamless bed), tempo (BPM 1-300), key (e.g. Cm; omit for any).

• Poll `action=status` yourself until complete: sound effects have no callback, so your

poll is what downloads the file.

• Saved to generated_music/sfx/<file>; not in the music player or action=list.
• The url that status returns (/generated_music/sfx/<file>) plays directly; add

?download=1 to save it. To bundle the clip with a canvas page instead, copy it and reference /canvas-data/<file>: mkdir -p ~/.openclaw/workspace/canvas-pages/_data && cp ~/.openclaw/workspace/generated_music/sfx/coin-pickup.mp3 ~/.openclaw/workspace/canvas-pages/_data/

• Generate once and reuse the file; never regenerate per play.

Direct API

POST /api/suno with JSON containing action (reads also work as GET /api/suno?action=...). Submit returns {"action":"generating","job_id":"...","task_id":"...",...}; any failure returns {"action":"error","response":"<reason>"}.

Song: action=generate

Model V5_5. Section tags like [Verse] are fine here because they are not inside a voice tag.

curl -s -X POST http://localhost:5001/api/suno \
  -H "Content-Type: application/json" -H "X-Agent-Key: ${AGENT_API_KEY:-}" \
  -d '{"action":"generate","title":"From Rooftops to Results","style":"country pop, upbeat","vocal_gender":"f",
       "lyrics":"[Verse]\nStarted on a roof with a hammer in hand\n[Chorus]\nFrom rooftops to results"}'

Jingle: {"action":"jingle","brand":"Acme Plumbing","style":"country","vocal_gender":"m","instrumental":false,"repeat":1} (also bare).

Poll: action=status

curl -s "http://localhost:5001/api/suno?action=status&job_id=$JOB_ID" -H "X-Agent-Key: ${AGENT_API_KEY:-}"

• Poll every 10-15 s until action is complete or failed. When the provider's callback

cannot reach this server (no public domain), polling is what saves the file, so an API job you never poll may never land.

• Always pass `job_id`; without it you get an arbitrary job.
• complete: title, url, duration_seconds (first reply), and a response to relay (for a

jingle it notes a long clip). failed: reason. not_found: wrong id or the server restarted (jobs live in memory); check action=list.

Lists and lookups

generated_music/ is /app/runtime/generated_music/ in the OVU container, ~/.openclaw/workspace/generated_music/ in the agent container, and runtime/generated_music/ in a native install. generated_metadata.json there holds per-file title, kind (song or jingle), lyrics, duration_seconds, suno_id, task_id and jingle fields. Read it; do not edit it.

Delivering a song (download link)

https://<your-domain>/generated_music/<filename>?download=1

• <filename> is the exact filename. ?download=1 saves the file; drop it to play inline.
• /generated_music/ is public even when login is required, so this is the link to text or email.
• A http://localhost:5001/... link only works on that machine.
• Latest song: the [Latest generated song: '<title>' (file: <file>) ...] line in your

context, or GET /api/music?action=latest.

• A song by name: look it up, never guess:

```bash curl -s "http://localhost:5001/api/suno?action=list" \

`` If several match (e.g. -2` variants), ask which one or offer the newest; give one link.

• The [Available tracks — ... Generated (N): ...] line lists titles for [MUSIC_PLAY:<title>],

not filenames.

• Never use /music/<file> for a generated song (that is the uploaded library and returns

{"error":"Track not found"}), never emit a [CANVAS:...] download page (none exists), never paste the whole list of URLs.

Editing existing songs

Name the source with filename (preferred; OVU finds its Suno ids), or audio_id / task_id, or song_url. Each returns a job_id; poll status; the result is a new track.