OpenAI-compatible speech API
Call POST /v1/audio/speech for buffered text-to-speech that returns one complete MP3, WAV, or PCM audio file.
POST /v1/audio/speech turns one piece of text into one audio file. For the fields v1 accepts it
follows the OpenAI speech request shape; an OpenAI client points its base URL at https://api.voice.humain.com/v1
and fills in Request below (a voice UUID is required for any non-default voice). The
service buffers the whole clip and returns it as a single body; this route never streams. For audio
that must arrive while it is still being made, use
Socket.IO text to speech.
This surface answers on voice-dev only today; staging and production come later. Everything below describes the development environment.
Authentication
Send your key in the x-api-key header, as on every other HTTP route
(Authentication). This route also accepts Authorization: Bearer <key>,
because OpenAI clients send the key only that way. For a static key, x-api-key wins when both
headers arrive.
Request
The request body is JSON.
| Field | Where | Required | Value |
|---|---|---|---|
model | Body | No | nebula only. Omitted, the deployment default (nebula) applies. A stale value from another provider, such as tts-1, returns 400 TTS_MODEL_NOT_FOUND. |
input | Body | Yes | The plain text to speak. Code-point limits apply on the server: 500 code points for free accounts and 1,000 for standard and enterprise accounts. See text-to-speech limits. |
voice | Body | No | A voice profile UUID, or an object {"id": "<uuid>"}. Omitted, or an empty string, the deployment's default voice speaks. Only UUID voices work on this surface in v1 (it doesn't accept voice-reference clone audio); any other present value, a name, null, or {}, returns 400. Pick a UUID from your environment's voice list; the values differ between environments, so the UUID below may not exist in yours. There is no HTTP voice-list route; list voices with the SDK or the Socket.IO voice event. |
response_format | Body | No | mp3 (default), wav, or pcm. opus, aac, and flac are rejected with 400. |
speed | Body | No | 1.0 only. Any other value returns 400. |
stream_format | Body | No | audio (default), which returns one complete file. sse is rejected with 400. |
instructions | Body | No | Not supported. A nonempty value returns 400. |
Idempotency-Key | Header | No | Absent or empty is ignored. A present key is 1 to 255 visible ASCII characters; anything else returns 400. A replayed response carries X-Idempotent-Replay: true, and it keeps the first attempt's X-Request-Id. See Idempotency-Key. |
Idempotency-Key
Idempotency-Key is optional and best effort. The replay cache lives in one pod's memory and holds
an entry for up to 10 minutes (current default; a completed entry can be evicted earlier when the
pod's memory budget or entry count is full), so the guarantee holds only when the retry reaches the
same pod while the entry survives:
- An identical retry that arrives while the first attempt is still running waits for it and gets the same audio bytes.
- An identical retry after the first attempt finished replays the stored bytes. You are not billed twice.
- The same key under a semantically changed request (the input, resolved model, voice, or canonical
format; reordered JSON keys alone do not change it) returns
409BILLING_IDEMPOTENCY_CONFLICT. Reusing the same key value from a different API key of the same account conflicts the same way. Send each distinct request under its own key. - Any cache miss runs as a new request and is billed as one: a retry that lands on another pod, a retry after the entry expired (10 minutes by default), a retry after the first attempt failed, a synthesized response over the cache's 8 MiB per-entry cap (current default), or a duplicate that arrives while the cache's waiter slots are saturated, or a completed entry evicted early when the cache's memory budget or entry count is full.
The replay row is scoped to your account (and its fingerprint to your API key), so the same key
value cannot resolve to another account's result. A replayed response carries the X-Idempotent-Replay: true header and keeps the
first attempt's X-Request-Id. Without Idempotency-Key, an SDK that retries an ambiguous request,
for example after a timeout, can be billed twice.
Response
A 200 response is the complete audio file as one binary body.
response_format | Media type |
|---|---|
mp3 | audio/mpeg |
wav | audio/wav |
pcm | audio/pcm |
pcm is raw PCM16 little-endian, 24 kHz, mono, with no WAV header. Every response from this
surface carries an X-Request-Id header, and an error body that sets job_id returns the same
value as the header. A gateway-layer rejection, for example on duplicated credential headers, can
arrive without the header. The audio response sets Cache-Control: no-store. One request returns
one complete file, never a partial stream.
Examples
Set $API_URL to your environment's API origin (https://api.voice.humain.com).
curl -sS -X POST "$API_URL/v1/audio/speech" \
-H "x-api-key: $API_KEY" \
-H "content-type: application/json" \
--data '{"model":"nebula","input":"Hello from HUMAIN Voice","voice":{"id":"42e38a63-849a-481a-b5bf-3c1b7a985de3"},"response_format":"mp3"}' \
--output speech.mp3The second example sends the key as a Bearer token and omits voice, so the deployment's default
voice speaks:
curl -sS -X POST "$API_URL/v1/audio/speech" \
-H "Authorization: Bearer $API_KEY" \
-H "content-type: application/json" \
--data '{"model":"nebula","input":"Hello from HUMAIN Voice","response_format":"wav"}' \
--output speech.wavThe OpenAI SDK works against the same route. Send Idempotency-Key through extra_headers:
from openai import OpenAI
import os
client = OpenAI(base_url=f"{os.environ['API_URL']}/v1", api_key=os.environ["API_KEY"])
speech = client.audio.speech.create(
model="nebula",
voice="af52a907-115e-4b25-9e44-11b70f655b71", # your environment's voice UUID
input="Hello from HUMAIN Voice.",
response_format="mp3",
extra_headers={"Idempotency-Key": "my-request-uuid-1"},
)
speech.stream_to_file("speech.mp3")The OpenAI SDK retries failed calls automatically (two by default) on statuses it picks, without
reading the body's retryable flag. The Idempotency-Key above rides along on those retries, so a
settled first response replays instead of billing again; one key belongs to one logical request, so
give every distinct request a fresh key. To follow the canonical retryable decision yourself, build
the client with max_retries=0.
Limitations
This is the v1 surface. It takes one model and one speed, accepts UUID voices only, and buffers the whole clip before it answers.
Emotion markup is processed with the same rules as the Socket.IO TTS surface (validated tags steer
speech; over-limit segments are rejected per the emotion rules in the canonical error table).
Shared limits and classes apply too: the request body cap is 16 MiB (current default,
environment-tunable), a synthesis over the deadline
renders TTS_DEADLINE_EXCEEDED (504 family), a voice UUID that does not exist answers 400
TTS_VOICE_NOT_FOUND, concurrency or balance refusals render the same codes as every public voice
path, and request validation renders four codes from the VALIDATION_ family:
VALIDATION_INVALID_FORMAT (malformed JSON, trailing garbage, or a null/{} voice value), VALIDATION_INVALID_PARAM (unsupported values such as speed, stream_format, or a nonempty instructions value),
VALIDATION_INVALID_UUID (a voice value that is not a UUID), and VALIDATION_REQUIRED_FIELD (an
empty input).
- A
speedvalue other than1.0. - A nonempty
instructionsfield. stream_format: "sse", and any other streaming delivery (Socket.IO text to speech).- The
opus,aac, andflacoutput formats. - Voice-reference clone audio; only a voice profile UUID works.
- Any
modelother thannebula.
Errors
Errors use the platform's canonical JSON error body, not the OpenAI error schema. Branch on code
and retryable, and keep the X-Request-Id header for support. A 400 covers the unsupported
values in Request: an unknown model, a response_format other than mp3, wav, or
pcm, a speed other than 1.0, a stream_format other than audio, or a nonempty instructions field.
A 409 means the idempotency key was reused with a different body or from a different API key of the
same account. Rejections before synthesis (validation, auth, and conflicts) release the credit hold;
a failure after synthesis started consumes it, and a cached replay is never billed twice. Every code,
limit, and retry rule is in Errors and limits.
Next steps
HTTP streaming API
Call the HUMAIN Voice HTTP streaming routes directly to transcribe a clip, stream live audio for transcription or speaker diarization, and capture text-to-speech frames.
Socket.IO API
Connect to HUMAIN Voice over Socket.IO and exchange the raw events and binary frames for fast transcription, realtime transcription, live diarization, voice lookup, and text to speech.