Generate audio
Convert text to speech and receive a temporary download URL for the MP3.
POST /v1/tts/generate
Request body
Swipe or scroll sideways to read all columns. With the table focused, use the left and right arrow keys.
| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Plain text to speak. HTML is stripped before the 4,000 UTF-16 code unit limit is counted. |
voice_id | string | Yes | Immutable voice_id from GET /v1/voices. |
language | string | No | Supported BCP 47 language tag for this voice. If omitted, the voice's default language is used. An unsupported value returns 400 invalid_request before charging quota. |
speed | number | No | Speaking speed from 0.5 to 2.0; defaults to 1.0. |
instructions | string | No | Optional speaking-style direction for voices that support it. |
The 4,000 unit text limit is counted after stripping HTML. Generating speech with a cloned voice counts twice the input length against quota. A voice's provider input-byte limit may impose a lower maximum. Send plaintext. Pitch and emotion controls are unsupported.
Example
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, welcome to Acoust.",
"voice_id": "v_Z2gBESGW6p2JmXWs",
"language": "en-US"
}' \
"https://api.acoust.io/v1/tts/generate"
Response
{
"audio_url": "https://storage.googleapis.com/...",
"expires_at": "2026-11-13T12:00:00.000Z",
"duration": 2.4,
"characters_used": 25,
"format": "mp3",
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"generation_outcome": "succeeded",
"quota_status": "charged"
}
Swipe or scroll sideways to read all columns. With the table focused, use the left and right arrow keys.
| Field | Type | Description |
|---|---|---|
audio_url | string | Temporary signed MP3 download URL. |
expires_at | string | ISO 8601 expiration time for the download URL (24 hours after generation). |
duration | number or null | Audio duration in seconds, when available. |
characters_used | number | Characters charged to quota, including the cloned-voice multiplier when applicable. |
format | string | Output format, mp3. |
request_id | string | Identifier for this request; it does not make retries idempotent or recover a result. |
generation_outcome | string | succeeded for this response. |
quota_status | string | charged for this response. |
Save the audio before the URL expires. Generation error responses use error: { code, message } and include request_id, generation_outcome, and quota_status; failed or uncertain 500 generation responses also include retry_safe: false. 400, 402, 403, and 429 generation errors do not include retry_safe. A generation error may have generation_outcome or quota_status set to unknown; a 500, timeout, or disconnect is not confirmation that generation failed or quota was refunded. Do not automatically resubmit: the original request may still have generated audio and charged quota, and a new request may charge again. Errors that occur before the generation route, such as authentication failures, may not include these diagnostics. See the error code table.
Code examples
Python
import requests
response = requests.post(
"https://api.acoust.io/v1/tts/generate",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"text": "Hello, welcome to Acoust.",
"voice_id": "Alison",
"language": "en-US",
},
)
response.raise_for_status()
data = response.json()
print(data["audio_url"]) # valid until expires_at
print(data["duration"]) # seconds, or None
JavaScript / Node.js
const response = await fetch("https://api.acoust.io/v1/tts/generate", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "Hello, welcome to Acoust.",
voice_id: "Alison",
language: "en-US",
}),
});
const data = await response.json();
if (!response.ok) throw new Error(data.error?.message ?? "Request failed");
console.log(data.audio_url, data.expires_at);
n8n (HTTP Request node)
- Method: POST
- URL:
https://api.acoust.io/v1/tts/generate - Authentication: Header Auth →
Authorization: Bearer YOUR_API_KEY - Body: JSON
{
"text": "{{ $json.text }}",
"voice_id": "Alison",
"language": "en-US"
}
Use GET /v1/voices to find supported voice IDs and languages. Treat the example voice ID as illustrative; use an ID returned for your account and selected language.