SpeechDto

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ditto-audio/json-schema/ditto-audio-speech-dto-schema.json",
  "title": "SpeechDto",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ditto-audio-openapi.json#/components/schemas/SpeechDto",
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "enum": [
        "kokoro",
        "xtts",
        "pocket"
      ],
      "description": "Model family. `kokoro` is fast, the cheapest, and English-leaning; `xtts` is expressive multilingual voice cloning; `pocket` reads each of its languages with a model trained on that language, from a short reference clip per voice (the most native voices). Optional: a named voice brings its own model, and with no voice named it is a preference for the one the server picks (ignored when that model cannot speak the language). The model used is echoed in `X-Ditto-Model`."
    },
    "voice": {
      "type": "string",
      "description": "Voice id from GET /v1/audio/voices (it must belong to `model` when you set both). Omit it, or send `default` / `auto` or a language tag such as `cs-CZ`, and the server picks the voice for the language (`language`, else the one the text is in): a NATIVE voice first, then the catalogue’s featured one, then by model (pocket, kokoro, xtts). GET /v1/audio/voices?language= names that pick as `defaultVoice`; the voice used is echoed in `X-Ditto-Voice`."
    },
    "gender": {
      "type": "string",
      "enum": [
        "female",
        "male",
        "neutral"
      ],
      "description": "With no voice named: prefer a voice of this gender among the native ones. Ignored when `voice` names one."
    },
    "input": {
      "type": "string",
      "maxLength": 8000,
      "description": "The text to speak."
    },
    "language": {
      "type": "string",
      "description": "BCP-47-ish language tag (or its name: `Czech`, `Čeština`); see GET /v1/audio/languages. AUTHORITATIVE for this request — it overrides the voice’s native language, which is how one XTTS voice speaks many languages. Omit it and we infer the language from `input`; text with no clear sign of its language is read in the voice’s own (the answer comes back in the X-Ditto-Language header)."
    },
    "response_format": {
      "type": "string",
      "enum": [
        "mp3",
        "mp3_64",
        "mp3_160",
        "wav",
        "wav24",
        "wav32f",
        "flac",
        "flac24",
        "pcm",
        "pcm_f32",
        "aiff",
        "caf",
        "au",
        "mulaw",
        "alaw"
      ],
      "default": "mp3",
      "description": "Audio encoding. Defaults to `mp3` (MPEG-2 Layer III, 24 kHz mono, 128 kbps).\n\n**Lossy, standard rate:** `mp3`, `mp3_64`, `mulaw`, `alaw`.\n**Lossless or uncompressed, 1.2× rate:** `flac`, `flac24`, `wav`, `wav24`, `wav32f`, `pcm`, `pcm_f32`, `aiff`, `caf`, `au`, `mp3_160`.\n\n`flac` is the one to pick for quality: lossless, and roughly half the size of `wav`. `wav32f` and `pcm_f32` are bit-exact with what the model produced; everything else quantizes those floats first. `pcm`/`pcm_f32` are HEADERLESS raw samples, not files.\n\nCommon spellings are accepted (`pcm_s16le`, `L16`, `.wav`, `u-law`, `aif`). `opus`, `aac` and `ogg` are NOT produced — the response says what to use instead. 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. See GET /v1/audio/format."
    },
    "stream": {
      "type": "boolean",
      "default": true,
      "description": "true (default): chunked transfer-encoding, bytes written as the model produces them. false: one buffered body with Content-Length."
    },
    "speed": {
      "type": "number",
      "default": 1,
      "minimum": 0.5,
      "maximum": 2,
      "description": "Speaking rate; >1 is faster."
    },
    "pauses": {
      "description": "Pauses placed between engine calls, in milliseconds. Long text is synthesized in several calls (by sentence: about 120 characters a call for xtts and pocket, 60 for Pocket Japanese and 75 for Pocket Korean; one sentence a call for kokoro) and joined; inside a call the model places every pause itself. Omit a field (or the whole object) and that join gets the pause the model itself leaves at that kind of boundary, scaled by `speed`. A value you set is exact: not scaled by `speed`. The pause is what a listener hears between the two words: whatever silence each side already ends or starts with counts toward it. The clip also ends with its last boundary's pause, so clips can be concatenated. Defaults at speed 1 (ms): `xtts`: sentence 540 (460 after ?, 500 after !), clause 330 (after a comma), paragraph 810; `kokoro`: sentence 430 (420 after ?, 440 after !), clause 150 (after a comma), paragraph 640; `pocket`: sentence 770 (850 after ?, 670 after !), clause 240 (after a comma), paragraph 1160.",
      "allOf": [
        {
          "$ref": "#/$defs/PausesDto"
        }
      ]
    }
  },
  "required": [
    "input"
  ],
  "$defs": {
    "PausesDto": {
      "type": "object",
      "properties": {
        "sentence": {
          "type": "number",
          "minimum": 0,
          "maximum": 5000,
          "description": "Milliseconds after a sentence (. ! ? …). Setting it sends every sentence as its own engine call, so EVERY sentence boundary gets exactly this pause instead of the model’s own."
        },
        "clause": {
          "type": "number",
          "minimum": 0,
          "maximum": 5000,
          "description": "Milliseconds where a sentence too long for one engine call is cut at a comma, semicolon, colon or dash. Commas inside a call are paced by the model and are not affected."
        },
        "paragraph": {
          "type": "number",
          "minimum": 0,
          "maximum": 5000,
          "description": "Milliseconds at a blank line in `input`."
        }
      }
    }
  }
}