Text-to-Speech API

The platform provides an AI Platform-compatible text-to-speech API. Availability depends on the group and model catalog of the current API key: first confirm in GET /v1/models that an available audio model exists, then call this API.

Request

Item	Value
Method	`POST`
Path	`/v1/audio/speech`
Authentication	`Authorization: Bearer <API_KEY>`
Request header	`Content-Type: application/json`
Response	Binary audio (not JSON)

The response is binary audio, not JSON — so use --output (or -o) to write the response directly to a file. Parsing it as JSON gives you an empty response body.

The available values for voice depend on the current model; not all models accept alloy.

Request

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Request parameters

Parameter	Type	Description
`model`	string	Required. The audio model `data[].id` returned by `GET /v1/models`.
`input`	string	Required. The text to synthesize. The length limit depends on the actual model.
`voice`	string	Voice name. Available voices depend on the current model; refer to the model details.
`response_format`	string	Output audio format, for example `mp3`. Supported formats depend on the actual model.
`speed`	number	Speech rate. Whether it is supported and the value range depend on the actual model.

The available ranges for voice, format, and speech rate vary by model. Do not assume all models support alloy or mp3, and do not hard-code one model's voice list in your code.

Response

Success

The body of a successful response is binary audio data, not JSON. Write it directly to a file or stream it to the client.

# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3

Failure

On failure, the API returns a non-2xx response with an error object, in the same structure as the model APIs:

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

Common causes of failure:

Situation	Symptom	Handling
No audio model in the group	`model_not_found` or the model is unavailable	Use `GET /v1/models` to confirm available audio models
Voice not supported by the model	`invalid_parameter`	Switch to a voice supported by that model
Format not supported by the model	`invalid_parameter`	Switch to a supported `response_format`
Requests too frequent	HTTP `429`	Back off and retry as instructed

Server-side integration recommendations

Text-to-speech is a synchronous API: the response is the audio data itself. When integrating, note the following:

Do not parse it as JSON. Check the HTTP status and Content-Type first, and read error as JSON only on failure;
Do not forget to set Content-Type when passing audio straight through to the browser, or the browser will treat it as text;
Control the length of input. For very long text, split it on your side, synthesize each segment, and then concatenate them, to avoid exceeding the limit in a single request;
Copy audio files to your own storage; do not depend on temporary results returned by the platform in the long term;
Your backend should cache frequently repeated synthesis results to avoid duplicate charges.

Async audio tasks

In addition to this synchronous API, the platform also provides async audio generation capabilities (such as background music and sound effects). The status and artifacts of these tasks are queried in the console's "Task Logs", and handling is similar to video tasks: save the task ID after creation, poll with the query API until the final state, and do not create duplicates.

Billing

Billing for the audio API is based on the model details in the model marketplace and may be charged per token, per call, or per duration. For billing and settlement rules, see Billing and Invoices.

On this page