API reference

Every endpoint of the Yoob voice API. All of them live under https://tts-api.yoob.com/v1 and take an API key as Authorization: Bearer …, except health.

Create speech

Turns text into audio. OpenAI-compatible, with Yoob's options added. See the text to speech guide.

curl https://tts-api.yoob.com/v1/audio/speech \
  -H "Authorization: Bearer $YOOB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "yoob-tts-1", "voice": "w1243", "input": "[joy] Hello!", "quality": "fast"}' \
  --output hello.wav

Response

The audio, with these headers:

content-type: audio/wav
x-request-id: req_b731ca0a249f49e69c89
x-yoob-seed: 1778055142
x-yoob-quality: fast
x-yoob-sample-rate: 48000
x-yoob-audio-seconds: 1.04
x-yoob-chunks: 1

x-yoob-audio-seconds is sent when the whole file is returned at once, not with stream.

Stream speech (WebSocket)

Voices text that is still being written, one connection per reply. Authenticate with the Authorization header, or put api_key in the config message. See Streaming text in.

The binary frames of all chunks together form one continuous stream. 30 s with no message counts as the end; at most 20,000 characters per connection; closing the socket cancels the reply.

Cancel speech

Stops a running speech request by the request_id you gave it, as a disconnect would but at once. Idempotent. A request cancelled before it starts streaming answers 409 request_cancelled.

{"cancelled": true}                           // running, and now cancelled
{"cancelled": false}                          // no running request has that id
{"cancelled": {"reply-41": false, "reply-42": true}}   // for request_ids

List voices

{
  "object": "list",
  "data": [
    {"id": "w1243", "object": "voice", "gender": "female", "tier": "product", "description": "Woman, mid twenties, American, mid-range pitch; breathy, intimate, hushed. ..."},
    ...
  ]
}

List models

Also GET /v1/models/yoob-tts-1 for one model.

{"object": "list", "data": [
  {"id": "yoob-tts-1", "object": "model", "created": 1760745600, "owned_by": "yoob"},
  {"id": "yoob-asr-1", "object": "model", "created": 1760745600, "owned_by": "yoob"}
]}

Create transcription

Transcribes audio in any common format, at most 25 MB: up to 60 minutes with yoob-asr-2, up to 60 seconds with yoob-asr-1. See the speech to text guide and emotion recognition.

curl "https://tts-api.yoob.com/v1/audio/transcriptions?response_format=json" \
  -H "Authorization: Bearer $YOOB_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @clip.wav

Response

{"text": "We still got some work to do and I look forward to getting that work done."}

verbose_json adds caption, segments (with caption, tags, emotion, emotion_probs, words, voice and p_human), words, duration and speaker. A full example is in the guide.

Stream transcription (WebSocket)

Live speech to text, up to 60 s of audio per session. Authenticate with the Authorization header, or send {"type": "auth", "api_key": "..."} as the first message. See Realtime.

wss://tts-api.yoob.com/v1/audio/transcriptions/stream

Anything else ends the session with an error (bad_message, or bad_frame for audio of the wrong shape). Events sent back are listed in Realtime events.

{"type": "ready", "id": "34f8d689b6b7", "sample_rate": 16000, "max_seconds": 60.0, "partial_every": 0.3}
{"type": "vad", "speech": true, "t": 0.064, "utt": 1}
{"type": "partial", "utt": 1, "start": 0.0, "end": 0.32, "caption": "[emo:neutral] Hello?", "text": "Hello?", "emotion": "neutral", ...}
{"type": "final", "utt": 1, "reason": "silence", "caption": "[emo:joy] Hello there. I am so happy you came today.", ...}
{"type": "final_meta", "utt": 1, "voice": {"f0_hz": 237.9, "wpm": 234.9, "snr_db": 56.9}, "p_human": 0.0002}
{"type": "speaker", "seconds": 4.5, "gender": {"m": 0.0069, "f": 0.9931, "o": 0}, "accent": {"us": 0.9953, ...}, ...}
{"type": "done"}

Duotone call (WebSocket)

A live voice call you can interrupt, one connection per call. Authenticate with the Authorization header, or put api_key in the config. See Use the Duotone socket.

{"type": "done", "usage": {"listened_seconds": 41.2, "spoken_characters": 612,
  "llm_input_tokens": 5120, "llm_output_tokens": 186, "llm": "yoob"}}

llm is yoob when Yoob's model wrote the replies, and yours when the config brought one; its tokens are then not billed. Calls end after 600 s.

Health

No key needed, and not under /v1: https://tts-api.yoob.com/health. Answers 200 when the service is ready and 503 otherwise.

{"status": "ok", "model": "yoob-tts-1", "queue": {"running": 0, "waiting": 0, "max_waiting": 16, "streams": 0, "max_streams": 16}}

Errors

Errors use OpenAI's shape. param names the field at fault, when there is one.

{"error": {"message": "'input' is required and must be a non-empty string.", "type": "invalid_request_error", "param": "input", "code": null}}

Rate limits

A 429 carries a Retry-After header in seconds; wait that long before retrying. For conversations, prefer the speech socket over one request per sentence: it counts once per reply.