DocsAPI reference

OpenAPI specification

Model IDs and options in examples are illustrative. Select an available model from GET /v1/models and check its capabilities and current prices.

Speech

POST /v1/audio/speech converts plain text to audio through an enabled speech provider. Provider models keep their provider identity. Eligible keys in your account are tried first and billed by your provider. When no usable BYOK key is available, or safe BYOK retries are exhausted, Ark uses its keys and charges your balance at the published rate, subject to access rules and spending limits.

curl https://ark.dewaweb.com/v1/audio/speech \
  -H "Authorization: Bearer ark_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-001" \
  -d '{"model":"google/gemini-3.8-flash-tts","input":"Selamat pagi dari Ark.","voice":"Kore","max_output_tokens":512,"response_format":"wav"}' \
  --output speech.wav

GET /v1/audio/voices?model= lists a speech model’s voices with their name, gender, languages, a short description and, where the provider publishes one, a sample clip URL. It needs no API key.

ParameterTypeDefaultDescription
modelstringrequiredAn available speech model.
inputstringrequiredThe text to speak, or for a model whose tts.input_mode is prompt, a description of the voices, lines and sounds to generate. Limited by tts.max_input_chars or tts.max_input_bytes.
voicestringmodel dependentA voice ID. Models with tts.voice_catalog list theirs at GET /v1/audio/voices?model=; others list them in tts.voices. Optional when tts.voice_required is false.
instructionsstringoptionalDelivery instructions, separate from the spoken text, where the model supports them; up to 2,000 UTF-8 bytes. style is accepted as an alias.
languagestringautoauto, when tts.auto_language is true.
response_formatstringwav where offeredOne of the model’s tts.formats: wav, mp3, opus (Ogg) or pcm (raw 16-bit mono at tts.sample_rate).
speednumber1Within tts.speed_range when the model has one; otherwise one of tts.speeds.
max_output_tokensintegermodel maximumFor models billed by output audio tokens: an audio-token ceiling that also limits the reservation.

No serving-mode parameter or default setting is needed. Speech tries each eligible BYOK key at most once within the request deadline before eligible paid fallback. Explicit credential, permission, quota and rate-limit rejections can permit fallback; ambiguous timeouts do not, to prevent duplicate generation. Existing idempotent requests retain their recorded billing outcome even if your keys change.

The example requests WAV audio. Check the selected model’s formats, voices, capabilities and published billing dimensions before sending it. Each billing dimension of the model is reported in its own header: X-Usage-Input-Tokens and X-Usage-Output-Audio-Tokens for token-metered speech, X-Usage-Characters for character-metered speech and X-Usage-Output-Audio-Ms for speech billed by generated duration. X-Audio-Duration-Seconds reports the duration of the returned audio. X-Credits-Charged reports the settled Ark charge, which is zero for BYOK.

Requests require a session or Ark API key and obey the applicable account and API-key limits. Workspace restrictions apply to requests made through that workspace. For paid requests, an estimated charge is held from your Ark balance before synthesis; BYOK requests do not reserve that balance. If audio is generated but settlement is delayed, the response carries X-Billing-Status: pending; settlement resumes without generating audio again. Streaming, SSML, reference audio and custom voices are not supported by this route; a prompt model can still describe several speakers in its prompt.

Save the returned audio. Reuse the same Idempotency-Key and request after a connection failure. Completed requests replay saved audio when content logging and retention permit it, without another generation or charge. Read status at GET /v1/audio/speech/requests/{id} and audio at GET /v1/audio/speech/requests/{id}/audio, using the response’s X-Request-ID. Audio that was not saved, expired or was deleted returns 410 audio_not_retained. The storage retention limit is seven days by default, or less under your content settings. An uncertain outcome requires reconciliation; submitting a new key can generate and bill again.