# Soundverse Enterprise API: agents.md

> A guide for AI agents, and the developers behind them, that call the Soundverse Enterprise API or
> work in its console at platform.soundverse.ai: how to authenticate, make calls, wait for results,
> pay for them and stay within the limits.

The Soundverse Enterprise API is a REST API for apps and platforms. It generates songs, music,
vocals, sound effects and stems, edits and analyses audio, runs ready-made workflows, Agent One and
Trace (music similarity search), and returns licensed results. Every call is asynchronous: you
create a job, then poll it or stream it. Calls are paid per use, in US dollars, from the API
account's own balance.

It is a separate product from the Soundverse app at www.soundverse.ai, which runs on a plan's
tokens. For the app, read https://www.soundverse.ai/agents.md. Companion files for this host:
[llms.txt](https://platform.soundverse.ai/llms.txt) (an index of every docs page) and the
documentation at https://platform.soundverse.ai/docs.

## Quick facts

| What | Where or how |
|---|---|
| Base URL | `https://apiv2.soundverse.ai` |
| Console | https://platform.soundverse.ai: Home, Pricing, Plans, Docs, API Keys and Billing |
| Documentation | https://platform.soundverse.ai/docs (the same pages are at https://www.soundverse.ai/docs) |
| Authentication | `Authorization: Bearer <API key>`; keys start with `sksoundverse_` |
| Format | JSON in and out. Every create call returns `201` with a job id at once |
| Results | Poll `GET /v1/generations/{id}`, or stream `GET /v1/generations/{id}/stream` (server-sent events) |
| Webhooks | None. Poll or stream |
| Retries | Send an `Idempotency-Key` header; a repeat within 24 hours returns the first job |
| Billing | Per call, in US dollars (the balance is kept in cents), priced by capability, version and license tier |
| Machine-readable spec | None is documented; the documentation pages are the reference |
| Health check | `GET /health`, the one route that needs no key |
| Contact | api@soundverse.ai; sales and custom terms: https://www.soundverse.ai/enterprise |

## Ground rules for agents

- **An API key is a password.** Keep it in an environment variable or a secret manager and send it
  only in the `Authorization` header. Never print it, log it, put it in a URL, commit it, paste it
  into a chat, ticket or prompt, or ship it in a browser or mobile app. Call the API from a server.
- **One key, one account.** Every key bills the same account balance. Never share a key between
  customers or apps you don't control, and never use a key you were not given.
- **A leaked key gets rotated.** In the console, API Keys → **Rotate** replaces it and shows the new
  key once; **Delete** revokes a key. Either way the old key stops working within about 30 seconds.
- **Every create call spends money.** It reserves the price from the balance before the job is
  queued. Check `GET /v1/account/balance` first, tell the user what a costly job will cost (a voice
  clone is $12.00; an Agent One run is metered), and set `max_budget` on Agent One runs.
- **Send an `Idempotency-Key` on every create call,** so a retry returns the original job instead of
  charging twice.
- **Respect the limits.** On `429 RateLimited`, back off and retry later with the same
  `Idempotency-Key`. Don't spread calls over extra keys or accounts to get round a limit, and don't
  poll in a tight loop.
- **Only upload what you have the rights to.** Upload audio only when the user owns it or has a
  license for it. A voice clone needs the speaker's consent and a written rights attestation.
- **Leave the human steps to the human.** Signing in, accepting the Terms of Service and paying in
  the console's checkout are the account owner's to do.

## Get access

1. Open https://platform.soundverse.ai and sign in with a Soundverse account, the same kind of
   account the app uses.
2. Choose **Get your API key**, then set up the enterprise account: a company name (optional) and
   your agreement to the [Terms of Service](https://www.soundverse.ai/terms-of-service).
3. On **API Keys**, choose **+ New**, name the key and create it. Copy it at once: it is shown only
   this one time.
4. Add funds. A new account starts with a balance of $0, and a call it can't pay for fails with
   `402 InsufficientFunds`.
   - **Plans** (https://platform.soundverse.ai/enterprise-platform/plans): monthly plans, each sized
     by a ×1 to ×5 level, whose monthly US-dollar credit equals the plan's price. Usage beyond the
     credit is billed automatically to the card on file at the plan's Extra Usage Cost rate, with no
     hard stop.
   - **Pay as you go:** a one-time top-up, on the Plans page or Billing → **Top up**. A top-up never
     expires, adds to any plan credit, and can be from $25 to $50,000 at a time.
5. **Billing** shows the balance and the usage history; **Pricing** and the docs list the prices.

## How a call works

Every generation follows the same four steps.

**1. Find the tool.** `GET /v1/tools` lists the tools this account can call, each with its `id`,
`name`, `operation`, `model`, `description` and `cost_unit`. Pick the entry whose `operation` and
`model` match the capability page in the docs. You can cache its `id`, but never hardcode one: look
it up again whenever a call returns `UnknownTool`.

**2. Create the job.** `POST /v1/generations` with three fields:
- `tool_id` (string, required);
- `license` (integer, optional; see [License tiers](#license-tiers); `1`, Royalty-Free, if omitted);
- `payload_json` (a string: the tool's input fields, JSON-encoded). It must be a string, not a
  nested object; a raw object fails.

```bash
curl -X POST https://apiv2.soundverse.ai/v1/generations \
  -H "Authorization: Bearer $SOUNDVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c1e-song-0001" \
  -d '{"tool_id": "<id from GET /v1/tools>", "license": 1,
       "payload_json": "{\"prompt\": \"upbeat synth-pop about a summer road trip\", \"versions\": 1}"}'
```

The answer is immediate: `201 {"task_id": "...", "status": "queued"}`. The call never waits for the
result.

**3. Wait for it.** Either:
- **Poll** `GET /v1/generations/{task_id}` every few seconds. `status` moves from `queued` to
  `processing`, then `completed` or `failed`. The response also has `tool_id`, `model`, `operation`,
  `error_message`, `created_at`, `completed_at` and, once there is one, `output`.
- **Stream** `GET /v1/generations/{task_id}/stream`, server-sent events: `progress`, `streaming_url`
  and `partial_output`, then one `terminal` event with the final `status` and `output`. Those
  events and a `timeout` event carry a `seq`; an `error` event (the relay broke) has none, and names
  the last one in its `message` instead. If the connection drops, or a `timeout` or `error` event
  arrives, reconnect with `?after=` set to the last `seq` you received. A stream ends with a
  `timeout` event after 10 minutes; reconnect the same way, or poll.

Billing settles whether or not you poll or stream to the end. A job that fails is refunded in full.

**4. Use the result.** `output` is the tool's own result. Audio and other files come as
`output.assets`, each with a `file_id`. To download one, call `GET /v1/files/{file_id}/url`: it
returns a signed `url` (with `mime_type` and `expires_at`) that works for about 10 minutes; mint a
new one rather than storing it. (Some docs pages name `/v1/files/{file_id}/download` instead; the
live API answers `/url`.) The `url` inside an asset is a private storage path, not a link. Files an
API call makes are saved, private, to the account's Soundverse Library, and a `file_id` can be the
input of a later call.

`GET /v1/generations` lists your jobs, newest first, 50 a page unless you set `page_limit`; for the
next page, pass the last job's `created_at` and `id` as `after_created_at` and `after_id`.

Some jobs have a route of their own and can't go through `POST /v1/generations`: a voice clone
(`POST /v1/voice-clones`) and audio inpainting (`POST /v1/audio-inpainting`) are refused there with
`422 InvalidGenerationInput`, and the workflows' engine with `400 UnknownTool`.

### Inputs: files and URLs

- Most capabilities that take audio accept it in any of three shapes: `{"url": "https://..."}` (or
  the bare URL string), `{"data_b64": "<base64>"}`, or `{"ref": "<file id>"}`. Each capability page
  names the field (`song`, `audio`, `vocal_reference`, …) and its limits.
- The dedicated routes below take an uploaded file id instead. Upload with `POST /v1/files`:
  - JSON `{"source_url": "https://...", "filename": "song.mp3"}`, which fetches the file from your
    URL; or
  - `multipart/form-data` with one `file` part.

  It returns `{"file_id", "filename", "size_bytes", "mime_type"}`. An upload can be up to 100 MiB,
  and each route has its own cap: 15 MiB for a voice clone's reference (MP3 or M4A only), 40 MiB for
  inpainting, 60 MiB for a workflow's song, 30 MiB for a hummed melody and 5 MiB for a MIDI file.

## Endpoints

| Method and path | What it does |
|---|---|
| `POST /v1/generations` | Create a job for any tool by `tool_id`. |
| `GET /v1/generations/{id}` | One job. `404 NOT_FOUND` if it doesn't exist, `403 FORBIDDEN` if another account owns it. |
| `GET /v1/generations` | Your jobs, paged. |
| `GET /v1/generations/{id}/stream` | Live progress (SSE). |
| `GET /v1/tools` | The tools this account can call. |
| `GET /v1/account/balance` | `total_effective`, `base_effective`, `extra_cents` and, for a plan's credit, `base_expires_at`. Amounts are US cents. |
| `POST /v1/files` | Upload a file; returns its `file_id`. |
| `GET /v1/files/{file_id}/url` | A short-lived download link for a file your account owns. |
| `POST /v1/voice-clones` | A reusable voice clone, with a consent record. |
| `GET /v1/voice-clone-consents/{consent_id}` | A clone's consent state. |
| `POST /v1/voice-clone-consents/{consent_id}/revoke` | Revoke the consent, which blocks future use of the voice. |
| `POST /v1/audio-inpainting` | Rewrite one section or time range of a song. |
| `POST /v1/song-translations`, `/v1/beat-swaps`, `/v1/karaoke-tracks`, `/v1/drumless-mixes`, `/v1/revoicings`, `/v1/instrument-layers`, `/v1/hummed-songs`, `/v1/trending-songs`, `/v1/voice-songs`, `/v1/genre-remixes`, `/v1/midi-songs`, `/v1/vocal-layers` | The 12 workflows (see [Workflows](#workflows)). |
| `/trace/v3/...` | Trace: datasets, uploads, ingestion, searches and jobs (see [Trace](#trace)). |

### Older URLs (compat routes)

Integrations written for the previous API keep working. These routes take the old field names, need
no `tool_id`, always run at the Royalty-Free tier, and return `201 {"job_id": "...", "status": "queued"}`.
Poll the `job_id` with `GET /v{5,6,7}/status?job_id=...` or `GET /v1/generations/{job_id}`.

- `POST /v{5,6,7}/generate/song`, `/generate/music`, `/generate/singing`, `/generate/remix` and
  `/extend/song`
- `POST /v5/extend/music` (also `/v1/generate/extend`) and `POST /v1/generate/lyrics`
- `GET /v5/recognize?audio_url=...` (a copyright check; it returns a job, not the answer)
- `POST /v1/generate/stem-separation/all-stems`, `/vocals`, `/instruments` and `/six-stem`

There are no blocking (`/sync`) routes. Some capabilities are native-only: audio transcription, audio
to prompt, sound effects, video to SFX, audio effects, similar music and MIDI to song. For another
license tier, or for a saved voice (`vocal_id`), use `POST /v1/generations`: the compat routes don't
pass either through.

### Model versions

Song, music and singing tools come in versions with the ids `v5`, `v6` and `v7`; `v7` is the newest.
These ids are the API's own. They are not the app's model names (Soundverse v9, Soundverse v8 and so
on), so don't translate one into the other.

## Capabilities

Each capability has a docs page with its fields, limits, examples and prices:

- [Song Generation](https://platform.soundverse.ai/docs/song-generation): from a prompt and lyrics, a reference song, a hummed melody or a MIDI file; 1–3 versions a call.
- [Music Generation](https://platform.soundverse.ai/docs/music-generation), [Singing Generation](https://platform.soundverse.ai/docs/singing-generation), [Extend](https://platform.soundverse.ai/docs/extend), [Remix](https://platform.soundverse.ai/docs/remix) and [Lyrics](https://platform.soundverse.ai/docs/lyrics).
- [Voice Cloning](https://platform.soundverse.ai/docs/voice-cloning): send `reference_file_id` (an uploaded MP3 or M4A of one voice; a clean 15–30 second recording works best), `consent: true` and a `rights_attestation`, and optionally `version` (`v5`, the default, `v6` or `v7`). The response carries a `consent_id`. Once the job completes, its `output.metadata_json` holds the saved voice's `vocal_id` (`sv_voice_...`): pass it as `vocal_id` in the payload of a song or singing call through `POST /v1/generations` to sing in that voice (melody and MIDI songs can't use it).
- [Audio Inpainting](https://platform.soundverse.ai/docs/audio-inpainting): new lyrics (up to 3,000 characters) for a named section or a time range of an uploaded song.
- [Stem Separation](https://platform.soundverse.ai/docs/stem-separation): 2 stems (vocals and instrumental), 6 stems, or 12 stems with MIDI.
- [Copyright / Recognition](https://platform.soundverse.ai/docs/copyright-recognition), [Transcription](https://platform.soundverse.ai/docs/transcription) and [Audio to Prompt](https://platform.soundverse.ai/docs/audio-to-prompt).
- [Sound Effects](https://platform.soundverse.ai/docs/sound-effects), [Video to SFX](https://platform.soundverse.ai/docs/video-to-sfx) and [Audio Effect](https://platform.soundverse.ai/docs/audio-effect).
- [Agent One](https://platform.soundverse.ai/docs/agent-one): see below.
- [Tool Catalog](https://platform.soundverse.ai/docs/tool-catalog): every callable tool with its prices.

### Agent One

An agent that plans and runs other tools for you. Call it through `POST /v1/generations` with the
`tool_id` of one of three tiers (operation `agent`, model `flash`, `standard` or `pro`); there is no
default tier. The payload takes `prompt` (required), and optionally `system_prompt`, `max_steps`
(0–50; 0 means the default) and `max_budget` (a cap on the run's total cost, in cents). The cap is
checked after each step settles, so a run stops once it reaches it, and what was spent stays charged.

The response's `output.text` is the agent's answer, and `output.metadata_json` is its full step
trace. Files it made appear there as `file_id`s; resolve them with `GET /v1/files/{file_id}/url`.

### Workflows

Fixed multi-step jobs, each on its own route: Song Translation, Similar Beat, Karaoke Instrumental,
Drumless Practice Mix, Revoice a Song, Add an Instrument Layer, Humming to Song, Trending Genre Song,
Song in Your Voice, Genre Remix, MIDI to Song and Add a Vocal Layer. Upload the input first with
`POST /v1/files`. A workflow returns a job like any other, and is billed per step at each step's own
price, with no quote up front. The docs list each one's steps.

### Trace

Music similarity search under `/trace/v3`, with the same key: create a dataset, upload and ingest
songs, then search one pair (1:1), one song against a dataset (1:N) or two datasets (M:N), with a
custom search, the comprehensive search or one of the eight use cases (cover, remix, genre, lyrics,
melody, sample, timbre and a deep comprehensive check). Searches return a `job_id`; poll
`GET /trace/v3/jobs/{job_id}` every 5–15 seconds. Polling is free, a job is billed by usage when it
completes (at least $0.03), failed jobs are not charged, and `budget_tokens` caps what one job may
cost, in cents. Start at https://platform.soundverse.ai/docs/trace.

## License tiers

Every call names the license its result is made under, and the price depends on the tier. The
console's Pricing page describes the ladder.

| `license` | Tier | What the Pricing page says it covers |
|---|---|---|
| `1` (or omitted) | Royalty-Free | Use without ongoing royalty obligations to Soundverse; the default and the cheapest tier |
| `2` | Standard | Broader usage rights for products and services built on the result |
| `3` | Distribution | Distributing the result commercially, such as releasing it to streaming platforms |
| `4` | Sync | Synchronizing the result with visual media: film, TV, ads and games |
| `5` | Master | Full, exclusive ownership of the result |

The dedicated routes take the same tiers as names: `"royalty_free"`, `"standard"`,
`"distribution"`, `"sync"` or `"master"`. The [Terms of Service](https://www.soundverse.ai/terms-of-service)
and the [Licensing Model](https://help.soundverse.ai/faqs/licensing-model) are the binding terms.

## Prices

Prices are per call (per song for song generation, and per second of video for Video to SFX), in US
dollars. These are the Tool Catalog's prices as of 5 November 2026;
https://platform.soundverse.ai/docs/tool-catalog is the current list, and the console's Billing page
shows what each call was charged.

| Capability | Royalty-Free | Master |
|---|---|---|
| Song generation, `v7`, per song | $0.12 | $1.67 |
| Song generation, `v6`, per song | $0.10 | $0.98 |
| Song generation, `v5`, per song | $0.07 | $0.70 |
| Music generation (any version) | $0.07 | $0.70 |
| Singing generation (any version) | $0.09 | $0.90 |

A song call with `versions: 3` makes three songs and costs three times the price.

The same price on every tier:

| Capability | Price |
|---|---|
| Voice clone | $12.00 |
| Audio inpainting | $1.00 |
| Sound effects | $0.54 |
| Remix | $0.30 |
| Audio to Prompt | $0.25 |
| Stem separation (2, 6 or 12 stems) | $0.10 |
| Extend | $0.07 |
| Copyright check, transcription, audio effect | $0.03 each |
| Lyrics | $0.02 |
| Video to SFX | $0.03 a second of video per take ($0.045 on model `v2`); keeping the dialogue adds $0.024 a second on model `v1` |

- **Agent One** is metered: a rate per input and output token and $0.001 per tool call, plus the full
  price of every tool the run calls.
- **Workflows** cost the sum of their steps; **Trace** jobs are billed by usage.
- The price is reserved when a job is created. A job that fails is refunded in full; a job priced by
  usage settles at what it used.

## Errors

A create call that the pipeline refuses returns `{"error": "<Name>", "message": "...", "retryable": true|false}`.
Branch on `error`, not on the status code alone.

| Status | `error` | What to do |
|---|---|---|
| 400 | `UnknownTool` | The `tool_id` (or model and operation) isn't callable. Look it up again in `GET /v1/tools`. |
| 400 | `MISSING_FIELD`, `UNSUPPORTED_REFERENCE` | A compat route is missing a field, or got a reference it can't use. Fix the request. |
| 401 | `UNAUTHENTICATED` | No `Authorization: Bearer` header. |
| 401 | `INVALID_API_KEY` | The key is wrong or revoked. |
| 402 | `InsufficientFunds` | The balance can't cover the price. Add funds, then retry. |
| 403 | `FORBIDDEN` | The job belongs to another account. |
| 404 | `NOT_FOUND`, `ResourceNotFound` | No such job, or no such file owned by this account. |
| 422 | `ToolNotPriced` | The tool has no price for that license tier. Choose another tier, or contact api@soundverse.ai. |
| 422 | `InvalidGenerationInput` | The payload failed validation; `message` names the field. |
| 429 | `RateLimited` | Too many calls for the hour or the day. Retryable: back off, then retry with the same `Idempotency-Key`. |
| 503 | `DependencyUnavailable` | A service the call needs is down for a moment. Retryable. |

The dedicated routes (voice clones, inpainting, the workflows) also refuse a body that doesn't match
their schema, such as a missing or unknown field, with `422` and a `detail` list naming the fields.
Only `RateLimited` and `DependencyUnavailable` are worth retrying unchanged. A job that is accepted
and then fails reports `status: "failed"` with an `error_message`.

## Rate limits

Limits are counted per account, per hour and per day, for each capability (shared by all its
versions) and for each model. Each window starts with the first call it counts and lasts an hour or
a day. A call over a limit gets `429 RateLimited`, and a refused call uses no quota. There are no
rate-limit headers, so the 429 is the only signal.

Soundverse sets the limits and can change them for a single account; no table of them is published.
A few docs pages give figures: the Agent One page lists `flash` 30 runs an hour and 150 a day, `standard`
20 and 100, and `pro` 10 and 50; the Audio to Prompt page 30 and 150; the Video to SFX page 20 and
100. Take them as a guide, not a promise: the limits on your account can differ, so handle a 429
whenever it comes. For higher limits, contact sales.

## Idempotency

Send `Idempotency-Key` (up to 200 characters of `A–Z a–z 0–9 _ . : -`) on any create call, native or
compat. A repeat with the same key within 24 hours returns the original job, without creating or
billing a second. Use a new key for each new job, and reuse it only to retry the same request. A
missing or malformed key isn't an error; the call just isn't deduplicated.

## MCP

The Soundverse MCP server, `https://mcp.soundverse.ai/mcp`, is for people working in an AI assistant
with their own Soundverse account. It signs in with OAuth and spends that account's plan tokens; it
does not take an Enterprise API key or use this balance. Setup: https://www.soundverse.ai/mcp. To
build on Soundverse from your own servers, use this API.

## Documentation

- [Overview](https://platform.soundverse.ai/docs): authentication, the request contract, errors, polling and streaming, results and rate limits.
- [Compat Routes](https://platform.soundverse.ai/docs/compat-routes) and [Tool Catalog](https://platform.soundverse.ai/docs/tool-catalog).
- One page per capability and workflow, and the Trace pages: [Overview](https://platform.soundverse.ai/docs/trace), [Datasets & Ingest](https://platform.soundverse.ai/docs/trace/datasets), [Search](https://platform.soundverse.ai/docs/trace/search), [Use Cases](https://platform.soundverse.ai/docs/trace/use-cases) and [Results & Billing](https://platform.soundverse.ai/docs/trace/results).
- [llms.txt](https://platform.soundverse.ai/llms.txt) lists every page.
- Product overview: https://www.soundverse.ai/api-info. Help center: https://help.soundverse.ai.
- In the help center, every API endpoint page except the Trace pages describes the older
  `api.soundverse.ai` API, not this one (songs, music, lyrics, extend, remix, singing, stems,
  recognition, loop and trim, the assistant), and so do the endpoint lists on its API Documentation
  page. The Trace pages describe this API.

## Reporting problems

- The API or the console: api@soundverse.ai, with the `task_id` or `job_id`, the time and the error
  body. Never include an API key.
- Billing and refunds for purchases on the web: support@soundverse.ai.
- Sales, higher limits and custom licensing: sales@soundverse.ai or https://www.soundverse.ai/enterprise.
- Rights and legal notices: legal@soundverse.ai.
