Prepare phrases ahead of time with /v1/prepare

Use POST /v1/prepare to queue up to 200 texts for background generation without billing. Ready phrases return instantly; queued texts are ready in a few seconds.

Short answer. POST /v1/prepare lets you queue up to 200 texts for background generation without being billed. Texts already in the library return instantly; new texts are generated in the background and ready in a few seconds, avoiding live generation delays when you call /v1/speak later.

Why prepare phrases

When you call /v1/speak with a new text, the API generates audio live. If you know which phrases you'll need ahead of time, /v1/prepare lets you generate them in the background so they're ready instantly when your app or agent needs them.

Preparing also helps you stay within live generation rate limits. Each account has a daily limit on how many new texts can be queued for live generation. By preparing phrases during off-peak times or in batches, you can spread the load and avoid hitting the limit when you need to speak urgently.

How /v1/prepare works

POST /v1/prepare takes a JSON body with three fields: voice, lang, and texts (a list of 1 to 200 texts, each 1 to 500 characters). The request is not billed.

Prepare up to 200 texts

curl -X POST https://speakvora.com/api/v1/prepare \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": "af_heart",
    "lang": "en",
    "texts": [
      "Welcome to our store.",
      "Your order is ready.",
      "Thank you for your purchase."
    ]
  }'

Understanding the response

The reply has four fields: ready, queued, rejected, and note.

ready: count of texts already in the library (these will return instantly from /v1/speak)
queued: count of texts being generated in the background (ready in a few seconds)
rejected: count of texts that failed validation (missing voice, invalid text, or other errors)
note: optional message with details about rejections

Calling /v1/speak after prepare

After /v1/prepare returns, queued texts are ready in a few seconds. When you call /v1/speak with the same text, voice, and language, the API returns the audio quickly without the live generation delay. Billing happens only when you speak the text, not when you prepare it.

Rate limits and daily quotas

POST /v1/prepare has a daily limit per account. If you exceed it, the API returns a 429 response with the error live_rate_limited. Plan your prepare requests to stay within the quota, or spread them across multiple days. This limit applies to new texts only; preparing texts already in the library does not count against it.

Error handling

If voice or texts are missing, or if you send more than 200 texts, /v1/prepare returns a 400 invalid_request error. Check that your voice ID is valid (for example, af_heart for English), your language code matches (en, es, fr, pt, hi, ja, zh), and each text is 1–500 characters.

Frequently asked questions

Is /v1/prepare billed?

No. POST /v1/prepare is not billed. You are billed only when you call /v1/speak to generate or retrieve the audio.

How long does it take for queued texts to be ready?

Queued texts are ready in a few seconds. After /v1/prepare returns, wait a moment and then call /v1/speak with the same text and voice; it will return quickly without the live generation delay.

What happens if I prepare the same text twice?

If a text is already in the library or has been prepared before, /v1/prepare counts it as ready (not queued) and does not generate it again.

Can I prepare more than 200 texts at once?

No. Each /v1/prepare request accepts 1 to 200 texts. If you need to prepare more, send multiple requests.

What does live_rate_limited mean?

Your account has hit its daily limit for new text generation. Wait until the next day or contact support. Preparing texts already in the library does not count against this limit.