Paxa Labs
Sign in

Synthesize speech (OpenAI-compatible)

POSThttps://api.paxalabs.com/v1/audio/speechOpen in playground

POST /v1/audio/speech serves the OpenAI audio.speech request shape with Paxa voices. Same pricing, headers, and error codes as /v1/tts; streaming by default.

View as Markdown
curl -X POST https://api.paxalabs.com/v1/audio/speech \
  -H "Authorization: Bearer $PAXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paxa-tts-flash-v2",
    "input": "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs",
    "voice": "khanomkrok"
  }' \
  --output speech.mp3

Point an OpenAI SDK at https://api.paxalabs.com/v1 and call audio.speech.create. The OpenAI compatibility guide covers the field mapping; timed speech and a pinned language use POST /v1/tts.

Headers#

authorizationBearer pxa_...Required

Authorization: Bearer pxa_... (recommended).

x-api-keypxa_...

Alternative to the Authorization header. Ignored when Authorization is present.

idempotency-keystring

Makes a retry safe: two requests carrying the same key are charged once. One request per key runs at a time. A concurrent duplicate answers 409 idempotency_in_flight. Reuse a key only to retry an identical request. A changed payload is rejected with 422. Accepts up to 200 printable ASCII characters other than space.

1 to 200 characterspattern ^[!-~]+$

Authentication

Body#

modelstringRequired

TTS model id, for example paxa-tts-flash-v2. OpenAI's tts-1, tts-1-hd, gpt-4o-mini-tts, gpt-4o-mini-tts-2025-03-20, gpt-4o-mini-tts-2025-12-15 are accepted and run on paxa-tts-flash-v2.

1 to 100 characters
inputstringRequired

The text to synthesize. Same limits, pricing, and tags as POST /v1/tts.

at least 1 character
voicestringRequired

The voice id from GET /v1/voices, for example "khanomkrok", or a designed voice id starting "voice_", resolved and billed as on POST /v1/tts. Case is ignored. OpenAI's voice names, such as alloy, are accepted and map to Paxa voices, and the x-voice-id response header names the voice that spoke.

1 to 100 characters
response_format"mp3" or "opus" or "wav" or "pcm" or "mulaw" or "alaw"

Audio container, as format on POST /v1/tts. Other OpenAI formats are not served and answer 400.

Default "mp3"
sample_rate8000 or 16000 or 22050 or 24000 or 32000 or 44100 or 48000

Sample rate of pcm and wav, in Hz. Paxa TTS Flash v2 serves 8000, 16000, 22050, 24000, 32000, 44100, 48000, and Paxa TTS Flash serves 24000 only. A Paxa extension to OpenAI's body. On this endpoint, formats other than pcm and wav ignore it, and any value must still be one of the listed rates. A rate the model doesn't serve answers unsupported_format. A request costs the same at every rate.

Example 16000
streamboolean

Streams the audio as it is synthesized, matching OpenAI delivery. Defaults to true. Set false to receive a complete body with a content-length.

Default true
stream_format"audio" or "sse"

The OpenAI field of the same name. The response is always the raw audio bytes under the audio content type of response_format, "sse" included. Read the content-type header before parsing events.

speednumber

Speaking rate, as a multiplier on the voice's own design speed. It runs from 0.5 to 1.5, and 1 is the voice as designed. Rate changes how the audio sounds. It does not change how many characters were sent. A request costs the same at every rate. Values round to the nearest 0.05. The OpenAI field of the same name. A value outside that range answers 400.

Default 1min 0.5max 1.5Example 1.1
temperaturenumber

Sets how much the pacing, pauses, breaths, and melody of a reading vary from one request to the next. It runs from 0 to 2, and 0.5 is the default. They vary least at 0 and most at 2. Paxa TTS Flash v2 reads it. Any other model accepts only a value that rounds to 0.5, and any other answers validation. A request costs the same at every temperature. Values round to the nearest 0.1. A Paxa extension to OpenAI's body, read as on POST /v1/tts.

Default 0.5min 0max 2Example 0.5

Response#

audio/mpeg or audio/ogg or audio/wav or audio/pcm;rate=24000;channels=1 or audio/basic or audio/x-alaw-basic The synthesized speech as binary audio, in the format and sample rate the request chose.

Response headers

HeaderDescription
x-request-idIdentifies the request for support and log correlation. Sent on every response, errors included, except the cached catalog (GET /v1/models, /v1/voices, /v1/audio/models, and /v1/audio/voices). Name it in request_ids when you send feedback about the request.
x-credits-chargedCredits charged for this request, exact to a hundredth. An idempotent replay reports the original charge. Sent on audio responses and on the OpenAI-compatible transcription endpoint, whose body follows OpenAI's shape and carries no usage object. POST /v1/translate, /v1/ocr, /v1/extract, /v1/stt, and /v1/voices/design report the charge in the usage object of the body instead.
x-voice-idThe id of the voice that spoke. When the request named the voice by an accepted alias, such as an OpenAI voice name, it is the Paxa voice the alias maps to. Sent on audio responses.
x-ratelimit-limitRequests per minute the plan allows.
x-ratelimit-remainingRequests left in the current minute window.
x-ratelimit-resetUnix time in seconds when the current window resets.

Errors#

400validationThe request body, query, or headers failed validation against the endpoint schema, or broke a rule the endpoint's reference states. A field the schema refused adds two fields to the problem body. path names the first failing field by location and name in dot form, such as body.voice or headers.idempotency-key. A body that could not be read gives the path body alone. reason is one stable code from the validation reasons list.
400unknown_modelThe model field does not name a served model.
400unsupported_formatThe model does not serve this format, or this format at the requested sample rate.
400unknown_voiceThe voice id names no voice on the model's roster and no designed voice this account holds.
400text_too_longThe text exceeds the model's per-request character ceiling.
400tag_invalidThe text holds a tag the model refuses. On Paxa TTS Flash v2, the bracket asks for what the model does not do, such as an accent, singing, or a sound outside the supported list. It can also hold no letters or carry a weight that is not a number. On a Paxa TTS Flash voice that takes emotion tags, the bracketed word is outside the tag list, or its weight is not a number. Nothing was charged.
401unauthorizedThe request carried no API key, or the key is invalid or disabled.
402insufficient_creditsThe account does not have enough credits for this request. Nothing was charged.
403key_limitThis API key reached its spending cap. Nothing was charged.
409idempotency_in_flightAnother request with this Idempotency-Key is in flight right now.
409idempotency_refundedThe original request under this Idempotency-Key failed and was refunded.
422idempotency_mismatchThis Idempotency-Key was already used for a different request.
422unspeakable_textThe text contains nothing the model can voice: only tags, emoji, punctuation, or a script it does not speak. A text of tags alone is refused before the charge; any other is charged and refunded.
429rate_limitedRequests per minute for the plan are exhausted. One window covers the whole account, across every product and every key.
429concurrency_limitedThe account holds the plan's full count of concurrent requests for this product. Nothing was charged. Each product is limited separately, and an open live connection holds one slot of its product for its lifetime.
500internalRequest state was inconsistent on the server.
502provider_errorModel inference failed after the request was charged.
503provider_unavailableThe model behind this endpoint is not available right now. Nothing was charged.
PreviousSynthesize speechNextLive speech