ตั้ง stream: true เพื่อรับเสียงเป็นช่วง (การสตรีมเสียง) และขอช่วงเวลาด้วย timestamps แนบ Idempotency-Key เพื่อส่งซ้ำได้อย่างปลอดภัย และข้อความที่ยาวเกิน max_chars ตอบ 400 text_too_long โดยไม่คิดเครดิต ส่วนเสียงที่อ่านแท็กอารมณ์หรือแท็กคำกำกับได้ แท็กที่เสียงอ่านไม่ได้ตอบ 400 tag_invalid โดยไม่คิดเครดิตเช่นกัน
เฮดเดอร์#
authorizationBearer pxa_...จำเป็นAuthorization: Bearer pxa_... (recommended).
x-api-keypxa_...Alternative to the Authorization header. Ignored when Authorization is present.
idempotency-keystringMakes 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.
เนื้อหา#
textstringจำเป็นThe text to synthesize, in Thai, English, Mandarin Chinese (Simplified script), or any mix of them. Cost is 10 credits per 1000 characters, billed per character and rounded up to the next hundredth of a credit, minimum 0.1 credit per request. At most 5,000 characters; longer text answers 400 text_too_long, and GET /v1/models reports each model's own ceiling as max_chars. On Paxa TTS Flash v2, every voice reads tags. A bracketed direction such as [whispering] sets the delivery from where it stands. A sound such as [laughs] plays where it is written, [pause] or [pause 300ms] adds silence, at most 500 ms for an exact length, and <emph> and <whisper> mark a span. A tag that model refuses, such as [british accent] or [sniffs], answers 400 tag_invalid. On a Paxa TTS Flash (paxa-tts-flash-v1) voice whose emotion_tags list is not empty, a bracketed tag such as [happy] or [sad:0.5] sets the delivery from where it stands. On those voices a tag outside the list, or a weight that is not a number, answers 400 tag_invalid. Every other v1 voice skips the tags it knows. Tag characters bill like the rest of the text.
voicestringจำเป็นThe voice id, the stable identifier GET /v1/voices lists, for example "khanomkrok". Case is ignored, and only the id is matched. A designed voice has an id starting "voice_", and GET /v1/voices/designed lists the account's. It speaks only on Paxa TTS Flash v2 (paxa-tts-flash-v2) and only for the account that saved it; on another model or account, or once deleted, it answers 400 unknown_voice. Speech in a designed voice bills at 1.25x the model's per-character rate, or 1.5x with timestamps.
modelstringจำเป็นTTS model id, for example paxa-tts-flash-v2. GET /v1/models lists the served catalog.
format"mp3" or "opus" or "wav" or "pcm" or "mulaw" or "alaw"Audio format. mp3 is compressed and the default. opus is Ogg Opus, 48 kbps on Paxa TTS Flash and 64 on Paxa TTS Flash v2, the smallest, for streaming and web playback. wav is uncompressed 16-bit PCM under a RIFF header, the largest, for audio that feeds further processing. pcm is those samples with no header, 16-bit little-endian mono, for voice agents and phone systems that take raw samples. Both are 24 kHz unless sample_rate says otherwise. mulaw and alaw are G.711 mu-law and A-law with no header, one byte per sample at 8 kHz, for phone lines. Paxa TTS Flash v2 serves them, and Paxa TTS Flash answers unsupported_format.
sample_rate8000 or 16000 or 22050 or 24000 or 32000 or 44100 or 48000Sample 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. For any other format the value may only restate that format's own rate, which is 8000 for mulaw and alaw. A rate the model doesn't serve answers unsupported_format. A request costs the same at every rate.
streambooleanWhen true the audio arrives as a chunked stream while it is synthesized, lowering time to first byte. When false the response is a complete body with a content-length.
timestamps"word" or "sentence" or "utterance"Adds speech timing to the response: "word" times every word, "sentence" every sentence, "utterance" every continuous run of speech. When set, the response is application/json with base64 audio and timing spans, or application/x-ndjson events when stream is true, and the request bills at 1.25x the model's per-character rate.
speednumberSpeaking 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. Timing spans are measured against the audio that was produced. They already carry the rate.
language"auto" or "th" or "en" or "zh"Sets how codes, digits, and symbols are read. Words keep the language of their script, and a number inside Thai or Chinese text keeps that text's language. Elsewhere, "th" reads them in Thai (AB2039 with Thai letter names and digits) and "en" in English. "zh" reads codes in English, a number next to Chinese characters in Mandarin, and other digits and symbols in Thai. "auto", the default, takes the language most of the text is written in, counting English only in words of three or more letters, and Thai on a tie. Under "auto", a bare number, AB2039, or 250 ml reads as Thai, and ISO9001 or 100 USD as English. Text with no Thai, Chinese, digits, or counted English word reads as English when a two-letter word has a lowercase letter, such as Hi or I'm OK. Pin "th" or "en" to choose how a short number or code reads. A request costs the same in every language. Every value but "auto" is a code GET /v1/voices reports as a voice's language. POST /v1/audio/speech ignores this field and reads every request as "auto".
temperaturenumberSets 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. POST /v1/audio/speech and the start frame of WS /v1/tts/live read it too.
การตอบกลับ#
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.
เฮดเดอร์ของการตอบกลับ
| เฮดเดอร์ | คำอธิบาย |
|---|---|
| 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. |
เมื่อเปิดไทม์สแตมป์#
application/json When timestamps is set, the response body is JSON carrying the audio and its timing. The status and the headers are unchanged.
audiostringจำเป็นThe complete audio file in the requested container, base64-encoded.
timingobjectจำเป็นดูฟิลด์ย่อยซ่อนฟิลด์ย่อย
timing.granularity"word" or "sentence" or "utterance"จำเป็นThe granularity that was requested.
timing.spansarray of objectsจำเป็นSpans in text order, together covering the spoken input.
ดูฟิลด์ย่อยซ่อนฟิลด์ย่อย
timing.spans[].textstringจำเป็นThe spoken input text this span covers. An emotion tag takes no span.
timing.spans[].startnumberจำเป็นWhere the span begins in the audio, in seconds.
timing.spans[].endnumberจำเป็นWhere the span ends in the audio, in seconds.
application/x-ndjson One JSON event per line, arriving as audio is synthesized. Each chunk carries the spans its own audio completed. The stream ends with a done event. A mid-stream failure ends it with an error event and refunds the charge automatically.
chunkOne NDJSON line of the streamed timed response.
type"chunk"จำเป็นaudiostringจำเป็นAudio chunk in the requested container, base64-encoded. Decode each chunk and concatenate the bytes in arrival order; never concatenate the base64 strings themselves. Empty on a line that only carries spans completed after the last audio.
spansarray of objectsจำเป็นSpans newly completed by the audio delivered up to and including this chunk; empty when this chunk completes none.
ดูฟิลด์ย่อยซ่อนฟิลด์ย่อย
spans[].textstringจำเป็นThe spoken input text this span covers. An emotion tag takes no span.
spans[].startnumberจำเป็นWhere the span begins in the audio, in seconds.
spans[].endnumberจำเป็นWhere the span ends in the audio, in seconds.
doneThe final NDJSON line. Every span already arrived on the chunk lines. This event carries their count and never repeats them.
type"done"จำเป็นgranularity"word" or "sentence" or "utterance"จำเป็นThe granularity that was requested.
span_countintegerจำเป็นHow many spans the chunk lines delivered in total. Compare it with the spans you collected.
errorSynthesis failed after delivery began. The charge is refunded automatically; this is the final line of the stream.
type"error"จำเป็นerrorobjectจำเป็นRFC 9457 problem details at the minimum shape, served with content type application/problem+json. Responses carry no prose: the errors reference is the documentation for every code. One code, 400 schema_invalid, adds two fields so a caller can fix the schema without guessing: path and reason.
ดูฟิลด์ย่อยซ่อนฟิลด์ย่อย
error.titlestringจำเป็นStable machine-readable error code, for example "insufficient_credits". Branch on this field; the errors reference documents every code's meaning and the recommended handling.
error.statusintegerจำเป็นHTTP status code, mirrored from the response.
error.pathstringPresent on 400 schema_invalid alone. Names the schema field the reason applies to, in dot form ("line_items[].amount"), or an empty string for the schema as a whole.
error.reasonstringPresent on 400 schema_invalid alone. One stable code from the schema reasons list in the Document Extraction reference, naming what is wrong at path.