API reference / Errors

Errors#

Errors use the ZeliSpeech error envelopes, so client error handling works unchanged. There are two shapes: a logical-error object for API errors and the pydantic detail array for request-validation errors.

Logical errors#

Auth, format, voice, and engine errors return a detail object:

{ "detail": { "status": "invalid_output_format", "message": "..." } }

Validation errors#

A malformed request body (for example a missing required text) returns the pydantic detail array with 422:

{
  "detail": [
    { "loc": ["body", "text"], "msg": "field required", "type": "value_error.missing" }
  ]
}

Tolerant request bodies#

Most "unexpected field" cases are not errors here. Fields the engine doesn't use (pronunciation_dictionary_locators, apply_text_normalization, optimize_streaming_latency, unknown model_id, …) are accepted and ignored rather than rejected, so an existing request body won't 422. See Create speech.

Handling errors#

import httpx
 
r = httpx.post(
    "https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1",
    params={"output_format": "mp3_44100_128"},
    headers={"Authorization": "Bearer sk-zeli-..."},
    json={"text": "Hello."},
)
if r.status_code >= 400:
    detail = r.json().get("detail")
    if isinstance(detail, list):
        print("validation error:", detail)
    else:
        print(detail["status"], detail["message"])
else:
    open("out.mp3", "wb").write(r.content)

const res = await fetch(
  "https://voice.your-domain.com/v1/text-to-speech/zeli-voice-1?output_format=mp3_44100_128",
  {
    method: "POST",
    headers: { "Authorization": "Bearer sk-zeli-...", "Content-Type": "application/json" },
    body: JSON.stringify({ text: "Hello." }),
  }
);
if (!res.ok) {
  const { detail } = await res.json();
  if (Array.isArray(detail)) console.error("validation:", detail);
  else console.error(detail.status, detail.message);
}