{"openapi":"3.1.0","info":{"title":"Voizum Text to Speech API","version":"1.0.0","description":"Turn text into natural speech (MP3) with your own cloned voices, in 7 languages. Asynchronous: create a job, check its status, download the audio. Billed in the same credits as the web app: 60 credits per 1,000 characters, minimum 100 per request. Human docs: https://voizum.com/docs · For AI assistants without code, use the MCP connector at https://voizum.com/mcp.","contact":{"url":"https://voizum.com/docs"}},"externalDocs":{"description":"Voizum API documentation","url":"https://voizum.com/docs"},"servers":[{"url":"https://voizum.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/status":{"get":{"operationId":"getStatus","summary":"Service health","security":[],"responses":{"200":{"description":"Operational","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["operational","degraded"]},"version":{"type":"string"}}}}}},"503":{"description":"Degraded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"degraded"},"version":{"type":"string"}}}}}}}}},"/account":{"get":{"operationId":"getAccount","summary":"Credit balance and pricing of the key's account","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices":{"get":{"operationId":"listVoices","summary":"Voices in your library (their `id` is the `voice_id` to generate)","description":"Only the voices saved in your account. To use a voice from the public library, add it to “My voices” in the web app first.","responses":{"200":{"description":"Voices","content":{"application/json":{"schema":{"type":"object","properties":{"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}}}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tts":{"post":{"operationId":"createSpeech","summary":"Create an audio from a text","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Retrying with the same key returns the same job and never charges twice (the key is per account; it doesn't compare the body)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","voice_id"],"properties":{"text":{"type":"string","minLength":1,"maxLength":600000},"voice_id":{"type":"string","description":"From GET /voices."},"speed":{"type":"number","minimum":0.5,"maximum":2,"description":"Speaking speed (1 = the voice's natural pace)."},"pause_ms":{"type":"integer","minimum":0,"maximum":800,"description":"Pause between sentences, in milliseconds."},"language":{"type":"string","enum":["auto","es","en","de","fr","pt","it","ru"],"description":"Language of the text. Omit it or use `auto` to detect it from the text."},"loudness_normalization":{"type":"boolean","description":"Level the output to a fixed loudness so every voice sounds equally loud."},"webhook_url":{"type":"string","format":"uri","maxLength":500,"description":"Public https URL. We POST a `generation.finished` event when the job ends (3 attempts, 10 s timeout). The event is not signed: confirm with GET /tts/{job_id}."}}}}}},"responses":{"200":{"description":"Same Idempotency-Key: the existing job, not charged again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"202":{"description":"Job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"400":{"description":"`parametros_invalidos`, `texto_demasiado_largo`, `webhook_invalido` or `voz_sin_muestra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`saldo_insuficiente`: includes `credits_needed` and `credits_available`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`voz_no_encontrada`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`limite_peticiones` (wait `Retry-After`) or `demasiados_en_cola` (too many jobs in progress: wait for some to finish).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`mantenimiento` or `servicio_no_disponible`: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listJobs","summary":"Your latest jobs, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`next_cursor` from the previous page."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Status"}}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tts/{job_id}":{"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getSpeech","summary":"Status of a job (poll every few seconds until `done`)","responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`no_encontrado`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelSpeech","summary":"Cancel a job that hasn't started yet (all its credits are returned)","responses":{"200":{"description":"Canceled","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"const":"canceled"}}}}}},"400":{"description":"It already started or finished: it can't be canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`no_encontrado`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tts/{job_id}/audio":{"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"download","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Force a download instead of inline playback."}],"get":{"operationId":"getSpeechAudio","summary":"The MP3 of a finished job (redirects to the file)","description":"The MP3 is kept for 4 days; after that this returns 404. Download and store it yourself.","responses":{"302":{"description":"Redirect to the MP3. Follow redirects (curl -L)."},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`no_encontrado`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (`limite_peticiones`): wait the seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tts/batch":{"post":{"operationId":"createSpeechBatch","summary":"Several separate audios in one request, with a single minimum charge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":2,"maxItems":100,"items":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":600000},"voice_id":{"type":"string","description":"Overrides the top-level voice_id for this item."}}}},"voice_id":{"type":"string","description":"Voice for every item (each item may set its own)."},"speed":{"type":"number","minimum":0.5,"maximum":2,"description":"Speaking speed (1 = the voice's natural pace)."},"pause_ms":{"type":"integer","minimum":0,"maximum":800,"description":"Pause between sentences, in milliseconds."},"language":{"type":"string","enum":["auto","es","en","de","fr","pt","it","ru"],"description":"Language of the text. Omit it or use `auto` to detect it from the text."},"loudness_normalization":{"type":"boolean","description":"Level the output to a fixed loudness so every voice sounds equally loud."}},"description":"Up to 1,200,000 characters in total."}}}},"responses":{"202":{"description":"Batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreated"}}}},"400":{"description":"`lote_invalido`, `texto_demasiado_largo`, `parametros_invalidos` or `cuerpo_invalido`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`saldo_insuficiente`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`requiere_compra`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`voz_no_encontrada`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`limite_peticiones` (wait `Retry-After`) or `demasiados_en_cola` (too many jobs in progress: wait for some to finish).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`mantenimiento` or `servicio_no_disponible`: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tts/dialogue":{"post":{"operationId":"createDialogue","summary":"One audio with several voices taking turns (podcasts, scenes, ads)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["turns"],"properties":{"turns":{"type":"array","minItems":2,"maxItems":100,"items":{"type":"object","required":["voice_id","text"],"properties":{"voice_id":{"type":"string"},"text":{"type":"string"}}}},"speed":{"type":"number","minimum":0.5,"maximum":2,"description":"Speaking speed (1 = the voice's natural pace)."},"pause_ms":{"type":"integer","minimum":0,"maximum":800,"description":"Pause between sentences, in milliseconds."},"language":{"type":"string","enum":["auto","es","en","de","fr","pt","it","ru"],"description":"Language of the text. Omit it or use `auto` to detect it from the text."},"loudness_normalization":{"type":"boolean","description":"Level the output to a fixed loudness so every voice sounds equally loud."},"match_voice_levels":{"type":"boolean","default":true,"description":"Match the volume between voices."},"expressiveness":{"type":"number","minimum":0.8,"maximum":1,"default":0.9}},"description":"Up to 5 different voices; the whole script up to 600,000 characters. Billed as one audio, with one minimum."}}}},"responses":{"202":{"description":"Dialogue created","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"const":"queued"},"credits_charged":{"type":"integer"},"turns":{"type":"integer"},"voices":{"type":"integer"},"eta_seconds":{"type":["integer","null"]}}}}}},"400":{"description":"`dialogo_invalido`, `texto_demasiado_largo`, `parametros_invalidos` or `cuerpo_invalido`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (`no_autorizado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`saldo_insuficiente`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`voz_no_encontrada`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`limite_peticiones` (wait `Retry-After`) or `demasiados_en_cola` (too many jobs in progress: wait for some to finish).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`mantenimiento` or `servicio_no_disponible`: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key (sk_voizum_…), created in the web app under API."}},"schemas":{"Status":{"type":"string","enum":["queued","processing","done","error","canceled"]},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["no_autorizado","parametros_invalidos","cuerpo_invalido","texto_demasiado_largo","lote_invalido","dialogo_invalido","webhook_invalido","voz_sin_muestra","saldo_insuficiente","requiere_compra","voz_no_encontrada","no_encontrado","limite_peticiones","demasiados_en_cola","mantenimiento","servicio_no_disponible"]},"message":{"type":"string"}},"additionalProperties":true}}},"Account":{"type":"object","properties":{"credits_remaining":{"type":"integer"},"credits_per_1000_chars":{"type":"integer"},"min_credits_per_request":{"type":"integer"},"max_chars_per_request":{"type":"integer"}}},"Voice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"}}},"JobCreated":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"const":"queued"},"credits_charged":{"type":"integer"},"eta_seconds":{"type":["integer","null"],"description":"Estimated seconds until it's ready (null if it can't be estimated)."}}},"JobSummary":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"},"credits_charged":{"type":"integer"},"duration_seg":{"type":["number","null"]},"voice_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Job":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"},"credits_charged":{"type":"integer"},"progress":{"type":"object","properties":{"parts_done":{"type":["integer","null"]},"parts_total":{"type":["integer","null"]},"percent":{"type":["integer","null"]}}},"created_at":{"type":"string","format":"date-time"},"eta_seconds":{"type":["integer","null"],"description":"While not finished."},"audio_url":{"type":"string","description":"When `done`: GET it with your key (it redirects to the MP3)."},"duration_seg":{"type":"number","description":"When `done`."},"error":{"type":"string","description":"When `error` (credits are returned automatically)."}}},"BatchCreated":{"type":"object","properties":{"batch_id":{"type":"string"},"status":{"const":"queued"},"credits_charged":{"type":"integer"},"minimum_applied_once":{"type":"integer"},"eta_seconds":{"type":["integer","null"]},"jobs":{"type":"array","items":{"type":"object","properties":{"job_id":{"type":"string"},"position":{"type":"integer"},"credits_charged":{"type":"integer"}}}}}}}}}