audio

Create an async batch synthesis job

Accepts up to 1000 items (200000 characters total) and returns IMMEDIATELY with a batch id — no audio in this response. Poll GET /v1/audio/batches/{id} for progress, then read GET /v1/audio/batches/{id}/items (or stream /output) for per-item results and presigned MP3 URLs.

Only SHAPE is validated here — an item with no resolvable model/voice, or a batch over the character ceiling, is rejected with a 400 naming the offending index, because a job guaranteed to fail entirely is not worth creating. Synthesis failures are per-item results discovered while running and never fail the batch.

Output audio is deleted at expiresAt (24h by default). The batch and its per-item accounting survive that; the MP3s do not.

Pass wait_ms (up to 30000) to wait for the batch in the same request: a batch of at most 20 items that finishes in time is answered with its items, so a short synthesis is ONE request. Batches of at most 3 items run on an interactive queue and never wait behind bulk work.

post/v1/audio/batches

Request

  • Base URL: https://api.ditto.audio (the document declares no server; this is the origin it was published from)
  • URL: https://api.ditto.audio/v1/audio/batches
  • Auth: HTTP bearer

Request body

model'kokoro' | 'xtts' | 'pocket'

Default model for every item that doesn’t set its own.

voicestring

Default voice for every item that doesn’t set its own.

languagestring

Default language. Omit to infer per item from its own text.

speednumber
response_format'mp3' | 'mp3_64' | 'mp3_160' | 'wav' | 'wav24' | 'wav32f' | 'flac' | 'flac24' | 'pcm' | 'pcm_f32' | 'aiff' | 'caf' | 'au' | 'mulaw' | 'alaw'

Default audio encoding for every item that doesn’t set its own. Every item is a COMPLETE file — real sizes in its header, not the streaming placeholder — so the result is directly playable and directly saveable. Hi-fidelity formats bill at 1.2× the normal rate, multiplied by the model’s own weighting — the audio is identical, but the bytes are several times larger. mp3 (the default), mp3_64, mulaw and alaw are unchanged at 1×. Each format’s exact multiplier is in GET /v1/audio/format and in the X-Ditto-Audio-Cost-Multiplier response header.

metadataobject

Opaque string map stored with the batch and returned on every read. We never interpret it — it exists so you can correlate a batch with whatever created it without keeping your own side table.

wait_msnumber

Wait up to this many milliseconds (max 30000) for the batch to finish before answering. A batch that finishes in time, with at most 20 items, is answered WITH its items (presigned URLs included), so one short synthesis costs one request. Otherwise the batch is returned as it stands; poll with GET /v1/audio/batches/{id}?wait_ms=.

Example request

{
  "model": "kokoro",
  "voice": "kokoro-af-heart",
  "language": "en",
  "items": [
    {
      "id": "para-17"
    }
  ],
  "metadata": {
    "project": "chapter-3",
    "requestedBy": "importer"
  }
}

Response

The created batch, status: "queued".

Changes

No recorded changes to this operation across all 1 revision of this API.