soundverse Capability
Agent One
An LLM agent that plans and calls the rest of the Enterprise API for you — generate a song, get vocals, add stems, and get album art from one natural-language request. Three tiers (flash / standard / pro), no compat route.
No compat route
Agent One only exists on the native pipeline — there is no old-style POST /v7/agent/... equivalent. Always call it via POST /v1/generations with the tier’s tool_id from Tool Catalog.
Tiers
Three separate tools, one per tier — each is its own tool_id, priced and rate-limited independently. Pick the tier per request; there’s no default.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| flash | model=flash | No | — | Fastest, cheapest. Good for quick tasks and simple tool orchestration (a single generation, a lookup, a short edit). |
| standard | model=standard | No | — | Balanced. The default choice for everyday multi-step orchestration (e.g. "make a song, then add album art and stems"). |
| pro | model=pro | No | — | Most capable. Complex, multi-step reasoning and orchestration — longer plans, more sub-tool calls, harder judgment calls. |
Calling Agent One
POST/v1/generationstool_id for (model, "agent") — pick a tier
curl -X POST https://apiv2.soundverse.ai/v1/generations \
-H "Authorization: Bearer sksoundverse_..." \
-H "Content-Type: application/json" \
-d '{
"tool_id": "<standard tier tool_id from /v1/tools>",
"payload_json": "{\"prompt\": \"Write and generate an upbeat pop song about summer road trips, then give it matching album art\"}"
}'payload_json must be a JSON-encoded string
On the native POST /v1/generations route, payload_json is a string field — a JSON object encoded as text, not a nested JSON object. Sending a raw object there fails with an unhandled error, not a clean 400. Double-encode it, as in the examples above.
Returns 201 {"task_id": "...", "status": "queued"} immediately, same as every other tool. Poll GET /v1/generations/{task_id} or open GET /v1/generations/{task_id}/stream for live progress — a run that generates a song and follow-up assets can take a while, so the stream is worth it here more than for a single-shot generation.
Input fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | The task or question for the agent to accomplish. |
| system_prompt | string | No | "" | Overrides the default agent persona, if you need custom instructions. |
| max_steps | integer | No | 0 | Cap on tool-using LLM steps. 0 = the worker's default. 0–50. |
| max_budget | integer | No | null | Optional hard cap on this run's total cost, in cents. See max_budget below. |
| workflow_build_only | boolean | No | false | Restrict the run to building and saving a reusable workflow (headless builder) rather than executing one. |
A few additional fields (studio, visualizer_*) exist for the Soundverse Studio UI’s own live-editing surface and aren’t meaningful outside it — leave them unset for a standard API integration.
Output
The response’s output.text is the agent’s final answer. output.metadata_json carries the full, replayable step trace: every sub-tool call the run made (which tool, its own tool_id-equivalent, status, and its own billed cost), interleaved prose segments, and self-verification notes on whether the run actually satisfied the request.
How sub-tool calls bill
This is the one thing about Agent One that’s genuinely different from every other tool on this site: a single agent run is not one flat charge. When the agent decides it needs a capability it doesn’t have itself — generating a song, searching the web, extracting stems — it dispatches a sub-tool call, and that sub-tool call is billed separately, at that tool’s own price, exactly as if you’d called it directly yourself.
Example, confirmed against a real run: a prompt that made the agent call the web-search sub-tool billed that call at web search’s own $0.01 flat price, as a separate line item from the agent’s own per-token orchestration fee below — not folded into one number, and not double-charged.
Not every tool the agent can reach is one you can call directly yourself, though — some exist purely to support the agent’s own orchestration (finding a reference by search, saving an in-progress workflow) and are intentionally left out of Tool Catalog and unavailable via a direct tool_id. You’ll see their cost show up in a run’s step trace like any other sub-tool call; you just can’t invoke them outside of an agent run.
max_budget
An optional hard cap on what a single run can spend, in cents, across its own orchestration fee and every sub-tool call it makes combined. Checked after each turn’s tool calls settle — a sub-tool’s real cost isn’t known until it completes, so this can’t be enforced before a call, only after. Once the cumulative cost reaches the cap, the run halts and reports it hit the budget; whatever was already spent stays charged. Omit it (the default) for an uncapped run.
Pricing
Each tier’s own orchestration fee — separate from whatever its sub-tool calls bill — is usage-based, not flat: an input-token rate, an output-token rate, and a flat per-sub-tool-call fee, all in USD (1 Soundverse token = $0.01).
| Tier | Per input token | Per output token | Per sub-tool call | Reserve floor |
|---|---|---|---|---|
| flash | $0.00000067 | $0.00000213 | $0.001 | $0.01 |
| standard | $0.00000122 | $0.00001355 | $0.001 | $0.02 |
| pro | $0.000006 | $0.00003 | $0.001 | $0.05 |
“Reserve floor” is a small up-front hold checked before the run starts, not the real per-call price — the real charge settles from actual token usage once the run finishes. Sub-tool calls the run makes bill separately, at their own listed price.
Rate limits: flash 30/hour, 150/day; standard 20/hour, 100/day; pro 10/hour, 50/day.