soundverse Workflow
Song in Your Voice
Generate a complete song in a chosen genre that sounds like the singer in a voice recording you upload. Lyrics can be supplied or written for you.
Dedicated route only
This workflow uses POST /v1/voice-songs. It runs a fixed multi-step pipeline; there is no generic tool_id for it.
Quickstart
POST/v1/voice-songssong in your voice
curl -X POST https://apiv2.soundverse.ai/v1/voice-songs \
-H "Authorization: Bearer sksoundverse_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: voice-song-001" \
-d '{
"voice_file_id": "018f0000-0000-7000-8000-000000000002",
"genre": "indie pop, upbeat",
"lyrics": "walking home\nunder city lights",
"license": "royalty_free"
}'The voice_file_id must be an active uploaded audio file owned by the authenticated enterprise account.
Getting a voice_file_id
Upload the file first via POST /v1/files — either {"source_url": "..."} if you already host it, or a multipart/form-data file part to upload bytes directly. Both return a file_id owned by your account, ready to pass here.
Request fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| voice_file_id | uuid | Yes | — | ID of a voice recording (at least 30 seconds of the singer) owned by the authenticated enterprise account (upload it first via POST /v1/files). Maximum 30 MiB. |
| genre | string | Yes | — | Genre and mood of the song (e.g. 'indie pop, upbeat'). |
| lyrics | string | No | — | The full lyrics to sing, line breaks included. Omit to have original lyrics written for you by the lyric writer (billed as one extra sub-call). |
| license | license tier | No | "royalty_free" | License tier to price and attach to every step of the pipeline. |
How it works
Each request runs 2 steps in order. The first is skipped when you supply lyrics:
- Writing lyrics for the song (skipped when you pass lyrics).
- Generating a song in the recorded singer’s voice.
Progress streams over GET /v1/generations/{task_id}/stream as each step starts and finishes.
Notes
Lyrics you pass are used as given. Omit lyrics and lyrics are written for you from the genre (one extra lyric-writer call).
Results and playback
Poll GET /v1/generations/{task_id} until the task is completed. The finished result is added to the authenticated account’s Soundverse Library. Enterprise API outputs are hidden from public/profile surfaces by default.
For API-only download, resolve the output’s file_id with GET /v1/files/{file_id}/url and use the returned short-lived signed URL.
Pricing
This workflow is priced pass-through: you are billed for each step the pipeline runs, at that step’s enterprise rate, in the license tier you requested. The pipeline itself adds no separate fee, and your billing ledger shows one entry per step. The steps that carry the cost are:
- Lyric writing (only when lyrics are omitted)
- Song generation from a voice reference (similar song)
There is no fixed per-request price; the total depends on the input and on which optional steps run.