Skip to content
Numes

API reference · Create speech

Media

Create speech

Convert text into spoken audio, streamed back as raw audio bytes.

POSThttps://api.numes.ai/api/v1/audio/speech

The response body is raw audio in the requested response_format (mp3, wav or pcm; mp3 by default), with the audio Content-Type and an X-Generation-Id header. Once audio has started, a failure ends the response early without an in-band error; check the generation's outcome to confirm a complete result. Voices depend on the model. Usage counts the input characters sent to the model, after your account's request policy applies its replacements, and output audio seconds. Guide: Speech and transcription.

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring

Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

Length1–128

Request body

application/json

The contract declares a 1 MiB body limit. The size the service enforces is listed in Limits.

modelstringRequired
Length≤ 393
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
inputstringRequired
Length1–4,096
voicestringRequired
response_formatenum<string>
Default"mp3"
One ofmp3pcmwav
speednumber
Default1
Range0.25–4

Responses

200Generated audio bytesaudio/mpegaudio/pcmaudio/wav

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

audio/mpeg — binary audio bytes.

audio/pcm — binary audio bytes.

audio/wav — binary audio bytes.

503No eligible provider can serve the request. Unknown, unpublished, currency-mismatched and unauthorized shared model IDs receive the same bounded response (`error.code` 503, `error.metadata.error_type` "provider_unavailable", message "no provider is available"). Inference and encrypted resolution do not classify model existence after routing fails. Earlier validation and authorization errors remain unchanged. An interrupted server execution while the original HTTP caller remains connected also uses 503 provider_unavailable with the fixed message "service temporarily unavailable". Once streaming has started, the error is in-band and the HTTP status remains 200. If an otherwise eligible USD-indexed Bitcoin offer is blocked by an unavailable market reference, or its reference expires before dispatch, the response instead uses 503 with error_type "bitcoin_reference_price_unavailable" and message "Bitcoin pricing is unavailable. Try again shortly."application/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject
ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

Retry-Afterinteger

Optional delay in seconds for retryable rate or availability errors.

Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject