# Text to speech, sound effects and music with Vimmerse's API

Vimmerse's audio API turns text into a finished audio file: a spoken line, a sound effect of a set length, or a music track with Lyria. Each call costs a number of credits at $0.03 per credit, and `POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/estimate-credits` returns that number before you pay. Send the request, pay the 402 price quote, and the response carries the file URL in `results`, with no job to poll.

## At a glance

- **Endpoints:** `POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-speech`, `POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-sound-effect`, `POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-music`
- **Speech body:** `prompt` (the text to speak). Optional: `voice` (default `AutoV`), `option` (default `ElevenLabsTTS`) and `language` (a code such as `en-US`, auto-detected when empty).
- **Price:** $0.03 per credit, pay as you go. The credits per call come from the estimate route.
- **Payment:** a 402, the price quote, which you pay and retry. Pay it over x402 or MPP, the wallet rails, which settle in USDC. Send your access token as `ZC-Agent-Authorization: Bearer`.
- **Response:** JSON with `status`, `mime_type`, `credits`, `args` and `results`, the list of file URLs. The file is finished when the call returns.
- **Limits:** for `ElevenLabsSE` sound effects, `duration` should be under 22 seconds.
- **Full purchase flow:** [the buyer skill](https://agents.vimmerse.net/zcj/vx84qmkuonyv/SKILL.md)

## Generate speech from text

1. Get an access token. The access token is the agent identity credential that the storefront issues. Register once, then exchange the stored assertion for a short-lived token. [auth.md](https://agents.vimmerse.net/zcj/vx84qmkuonyv/auth.md) has the commands. Send this token on every call below.

2. Estimate the credits:

   ```bash
   curl -s -X POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/estimate-credits \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"app_name": "text-to-speech", "option": "ElevenLabsTTS"}'
   ```

   The response is `{"total_credits": <credits>, "breakdown": {…}}`. The example estimate returned 4 credits and drew nothing. A call's cost is its credits times the rate. For 4 credits that is $0.12. `prompt` is optional here and sets length-based pricing where that applies, so send the text you plan to speak.

3. Send the speech request with your token:

   ```bash
   curl -s -i -X POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-speech \
     -H 'Content-Type: application/json' \
     -H "ZC-Agent-Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"prompt": "Welcome. This short line of speech was generated from text."}'
   ```

   The storefront answers `402` with `payment.amountUsd` and a challenge for each rail. The x402 challenge arrives in the `payment-required` header and the MPP challenge in `www-authenticate`. Nothing is charged yet.

   The token goes on the paid call so that the asset belongs to your identity rather than to the wallet.

4. Pay and resend the same request with the proof attached. On x402, put the signed payload in `x-payment`. On MPP, send `Authorization: Payment <credential>`. On either rail, keep the token in `ZC-Agent-Authorization`:

   ```bash
   curl -s -X POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-speech \
     -H 'Content-Type: application/json' \
     -H "ZC-Agent-Authorization: Bearer $ACCESS_TOKEN" \
     -H "x-payment: $X402_PAYLOAD" \
     -d '{"prompt": "Welcome. This short line of speech was generated from text."}'
   ```

   A standard x402 or MPP client signs the payment and resends for you. The example call was quoted the 4 credits its estimate returned and paid $0.12 over x402. It answered in 16.7 seconds with the finished file in the body, so set a client timeout well above that. The response has this shape:

   ```json
   {"id": "<asset_id>", "status": "success", "app_name": "text-to-speech", "mime_type": "audio/mp3", "credits": <credits>, "args": {"voice": "AutoV", "option": "ElevenLabsTTS", "language": ""}, "results": ["<file URL>"]}
   ```

5. Save the file from `results`:

   ```bash
   curl -sL "<file URL>" -o voice-line.mp3
   ```

## Sound effects and music

The sound effect and music routes take the same headers and the same 402 payment as speech. Price each one first with the estimate route and the matching `app_name`.

| Output | Route | Body | `option` | Estimate `app_name` |
| --- | --- | --- | --- | --- |
| Speech | `text-2-speech` | `prompt`, `voice`, `option`, `language` | `ElevenLabsTTS` (default), `AutoA`, `ChirpTTS`, `MinimaxTTS` | `text-to-speech` |
| Sound effect | `text-2-sound-effect` | `prompt`, `duration` (whole seconds, default 5), `option` | `MMAudio` (default), `ElevenLabsSE`, `AutoA` | `text-to-audio` |
| Music | `text-2-music` | `prompt` (a description of the music), `option` | `Lyria` (default), `AutoA` | `text-to-music` |

The following request estimates a sound effect of a given length:

```bash
curl -s -X POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/estimate-credits \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"app_name": "text-to-audio", "option": "ElevenLabsSE", "prompt": "a wooden door creaking open", "duration": 4}'
```

Then send `{"prompt": "a wooden door creaking open", "option": "ElevenLabsSE", "duration": 4}` to `https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-sound-effect`.

For music, send `{"prompt": "calm acoustic guitar for a podcast intro", "option": "Lyria"}` to `https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/text-2-music`. The music route returns a WAV file in `results`.

## Limits and charges

- Each generation request is one paid call.
- Credits per call depend on the `option`, the `prompt` and the `duration`. The estimate route gives the count that the call is charged.
- A 402 that you have not paid charges nothing, so you can safely stop there. Paying the 402 completes the purchase.
- Card pays only per-call amounts of $0.50 or more, and smaller calls are rejected. Pay a short line on a wallet rail or from prepaid credit.
- Prepaid credit starts at $14 on the Credits plan, at $28 per thousand credits. [The buyer skill](https://agents.vimmerse.net/zcj/vx84qmkuonyv/SKILL.md) covers buying it and topping it up.
- If a paid call times out, reconcile it before you retry. Do not pay twice for one request.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block | The price quote. Nothing is charged yet. | Pay on one rail and resend the same request. |
| `422` | A body field failed validation. | Fix the field named in `detail` and send again. |
| `401 invalid_token` | The token expired or did not verify. `reason` says which. | Exchange the stored assertion for a fresh token ([auth.md](https://agents.vimmerse.net/zcj/vx84qmkuonyv/auth.md)). |
| `invalid_token`, reason `combined_authorization_unsupported` | `Authorization` held both `Payment` and `Bearer`. | Move the token to `ZC-Agent-Authorization`. |
| `settlement_failed` | The payment did not settle. `settlementReason` says why. | Fix the wallet and start again for a fresh 402. |
| `payment_consumed` | That payment was already settled. | Check the original request's delivery before paying again. |

The full list is in the [error reference](https://agents.vimmerse.net/zcj/vx84qmkuonyv/errors.md).

## Frequently asked questions

### Can a text to speech API call be paid per request, with no subscription?

Yes. Each speech, sound effect or music call is paid on its own through a 402 over x402 or MPP, with no subscription. Send your access token alongside the payment so that the generated asset belongs to your identity.

### Does the speech route offer ElevenLabs voices?

Yes. `ElevenLabsTTS` is the default `option`. `ChirpTTS`, `MinimaxTTS` and `AutoA` are the other values. `voice` takes a voice ID or name and defaults to `AutoV`.

### How much does a line of speech cost?

The cost is the credits the estimate route returns, times $0.03 per credit. The 402 states the exact amount before you pay.

### Do I need to poll for the audio file?

No. Audio calls return when the file is ready, and the URL is in `results` in the same response.

### Can I see the credits for a sound effect or a music track before paying?

Yes. Send `POST https://agents.vimmerse.net/zcj/vx84qmkuonyv/v2/audio/estimate-credits` with `app_name` set to `text-to-audio` or `text-to-music` and the same `option`, `prompt` and `duration` you will send to the generation route.

## Keep reading

- [The buyer skill](https://agents.vimmerse.net/zcj/vx84qmkuonyv/SKILL.md): the full purchase flow
- [How to pay](https://agents.vimmerse.net/zcj/vx84qmkuonyv/payment.md): rails, credit plans and top-ups
- [Identity](https://agents.vimmerse.net/zcj/vx84qmkuonyv/auth.md): register and exchange an access token
- [AI Audio prices](https://agents.vimmerse.net/zcj/vx84qmkuonyv/services/audio): the price for each plan

---

Updated 2026-11-06. All Vimmerse guides: https://agents.vimmerse.net/guides.md. Storefront: https://agents.vimmerse.net/zcj/vx84qmkuonyv/llms.txt.