Skip to main content
POST
Generate speech audio from text
Generate natural-sounding speech from text. Supports preset voices, voice cloning, and voice design depending on the selected model. Returns a request_id for status polling.
Prerequisite: Consult the Model Selection endpoint to identify a valid model slug and the per-model voice catalog.
OpenAI SDK users: This endpoint is also available via the OpenAI-compatible surface as POST /v1/audio/speech at https://oai.deapi.ai/v1. The six OpenAI voice aliases (alloy, echo, fable, onyx, nova, shimmer) are supported on Kokoro. See OpenAI Compatibility.

Authorizations

Authorization
string
header
required

Sanctum personal access token, sent as Authorization: Bearer <token>. The token is opaque — it carries no claims and no embedded expiry, so do not attempt to decode it. Issue and revoke tokens from your account dashboard.

Headers

Accept
enum<string>
default:application/json
required
Available options:
application/json

Body

multipart/form-data

Audio generation parameters. Supports three TTS modes: custom_voice (default, preset speakers), voice_clone (clone from reference audio), voice_design (create voice from description).

text
string
required

Text to be converted to speech

Example:

"A beautiful sunset over mountains"

model
string
required

The model to use for speech generation. Available models can be retrieved via the GET /api/v2/models endpoint.

Example:

"Kokoro"

lang
string
required

Language to be used during audio generation

Example:

"en-us"

speed
number
required

Generated audio speech speed

Example:

1

format
string
required

Audio output format. Read info.limits.output_formats for your model from GET /api/v2/models and send one of the listed values; anything else is rejected with 422.

Example:

"mp3"

sample_rate
number
required

Sample rate of generated audio

Example:

24000

mode
enum<string> | null

TTS mode: custom_voice (default), voice_clone, or voice_design. Determines which fields are required.

Available options:
custom_voice,
voice_clone,
voice_design,
null
Example:

"custom_voice"

voice
string | null

Name of the voice to be used. Required for custom_voice mode.

Example:

"af_sky"

ref_audio
file | null

Reference audio file for voice cloning. Supported formats: mp3, wav, flac, ogg, m4a. Max 10MB. Duration must be between 3-10 seconds (model-specific limits may apply). Required for voice_clone mode.

ref_text
string | null

Optional transcript of the reference audio for improved voice cloning accuracy.

Example:

"Transcript of the reference audio clip"

instruct
string | null

Natural language voice description for voice_design mode (e.g. "A warm female voice with a British accent"), or style/emotion control in custom_voice mode.

Example:

"Read this in a calm, measured tone"

webhook_url
string<uri> | null

Optional HTTPS URL to receive webhook notifications for job status changes (processing, completed, failed). Must be HTTPS. Max 2048 characters. A per-request URL is self-contained: it is delivered even when the account has no webhook configuration, or the account webhook is disabled. See the webhooks block at the top level of this document for the event payloads and the headers each delivery carries.

Maximum string length: 2048
Example:

"https://your-server.com/webhooks/deapi"

webhook_secret
string | null

Optional per-request HMAC secret (min. 32 chars) used to sign the webhook callback. Overrides the account-default secret for this job only. If omitted, the account-default secret signs the callback; if no secret exists at all, the callback is still delivered but UNSIGNED (empty X-DeAPI-Signature header). Requires webhook_url to also be set.

Required string length: 32 - 255
Example:

"a1b2c3d4e5f60708091a2b3c4d5e6f7081920a1b2c3d4e5f60708091a2b3c4d5"

Response

ID of the inference request.

data
object
required

Information from success endpoint