API Guides

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.

FieldWhereRequiredValue
modelBodyNonebula only. Omitted, the deployment default (nebula) applies. A stale value from another provider, such as tts-1, returns 400 TTS_MODEL_NOT_FOUND.
inputBodyYesThe 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.
voiceBodyNoA 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_formatBodyNomp3 (default), wav, or pcm. opus, aac, and flac are rejected with 400.
speedBodyNo1.0 only. Any other value returns 400.
stream_formatBodyNoaudio (default), which returns one complete file. sse is rejected with 400.
instructionsBodyNoNot supported. A nonempty value returns 400.
Idempotency-KeyHeaderNoAbsent 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 409 BILLING_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_formatMedia type
mp3audio/mpeg
wavaudio/wav
pcmaudio/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.mp3

The 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.wav

The 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 speed value other than 1.0.
  • A nonempty instructions field.
  • stream_format: "sse", and any other streaming delivery (Socket.IO text to speech).
  • The opus, aac, and flac output formats.
  • Voice-reference clone audio; only a voice profile UUID works.
  • Any model other than nebula.

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

On this page