# Synthesize speech (OpenAI-compatible)

`POST https://api.paxalabs.com/v1/audio/speech`

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.

Point an OpenAI SDK at `https://api.paxalabs.com/v1` and call `audio.speech.create`. The [OpenAI compatibility guide](https://paxalabs.com/docs/openai-compatibility) covers the field mapping; timed speech and a pinned `language` use [POST /v1/tts](https://paxalabs.com/docs/api/text-to-speech).

## Headers

- `authorization` (Bearer pxa_..., required): Authorization: Bearer pxa_... (recommended).
- `x-api-key` (pxa_..., optional): Alternative to the Authorization header. Ignored when Authorization is present.
- `idempotency-key` (string, optional, 1 to 200 characters, pattern ^[!-~]+$): 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.

See authentication at https://paxalabs.com/docs/authentication.

## Body

- `model` (string, required, 1 to 100 characters): 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.
- `input` (string, required, at least 1 character): The text to synthesize. Same limits, pricing, and tags as POST /v1/tts.
- `voice` (string, required, 1 to 100 characters): 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.
- `response_format` ("mp3" or "opus" or "wav" or "pcm" or "mulaw" or "alaw", optional, default "mp3"): Audio container, as format on POST /v1/tts. Other OpenAI formats are not served and answer 400.
- `sample_rate` (8000 or 16000 or 22050 or 24000 or 32000 or 44100 or 48000, optional, example 16000): 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.
- `stream` (boolean, optional, default true): Streams the audio as it is synthesized, matching OpenAI delivery. Defaults to true. Set false to receive a complete body with a content-length.
- `stream_format` ("audio" or "sse", optional): 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.
- `speed` (number, optional, default 1, min 0.5, max 1.5, example 1.1): 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.
- `temperature` (number, optional, default 0.5, min 0, max 2, example 0.5): 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.

## 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.

| Header | Description |
| --- | --- |
| x-request-id | Identifies 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-charged | Credits 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-id | The 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-limit | Requests per minute the plan allows. |
| x-ratelimit-remaining | Requests left in the current minute window. |
| x-ratelimit-reset | Unix time in seconds when the current window resets. |

## Errors

- `validation` (400): The 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.
- `unknown_model` (400): The model field does not name a served model.
- `unsupported_format` (400): The model does not serve this format, or this format at the requested sample rate.
- `unknown_voice` (400): The voice id names no voice on the model's roster and no designed voice this account holds.
- `text_too_long` (400): The text exceeds the model's per-request character ceiling.
- `tag_invalid` (400): The 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.
- `unauthorized` (401): The request carried no API key, or the key is invalid or disabled.
- `insufficient_credits` (402): The account does not have enough credits for this request. Nothing was charged.
- `key_limit` (403): This API key reached its spending cap. Nothing was charged.
- `idempotency_in_flight` (409): Another request with this Idempotency-Key is in flight right now.
- `idempotency_refunded` (409): The original request under this Idempotency-Key failed and was refunded.
- `idempotency_mismatch` (422): This Idempotency-Key was already used for a different request.
- `unspeakable_text` (422): The 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.
- `rate_limited` (429): Requests per minute for the plan are exhausted. One window covers the whole account, across every product and every key.
- `concurrency_limited` (429): The 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.
- `internal` (500): Request state was inconsistent on the server.
- `provider_error` (502): Model inference failed after the request was charged.
- `provider_unavailable` (503): The model behind this endpoint is not available right now. Nothing was charged.

## Example

curl:

```bash
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
```

TypeScript:

```typescript
import { writeFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.paxalabs.com/v1",
  apiKey: process.env.PAXA_API_KEY,
});

const response = await client.audio.speech.create({
  model: "paxa-tts-flash-v2",
  voice: "khanomkrok",
  input: "สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs",
});

await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));
```

Python:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.paxalabs.com/v1",
    api_key=os.environ["PAXA_API_KEY"],
)

with client.audio.speech.with_streaming_response.create(
    model="paxa-tts-flash-v2",
    voice="khanomkrok",
    input="สวัสดีครับ ยินดีต้อนรับสู่ Paxa Labs",
) as response:
    response.stream_to_file("speech.mp3")
```