Skip to main content

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.

FieldTypeRequiredDescription
textstringYesPlain text to speak. HTML is stripped before the 4,000 UTF-16 code unit limit is counted.
voice_idstringYesImmutable voice_id from GET /v1/voices.
languagestringNoSupported 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.
speednumberNoSpeaking speed from 0.5 to 2.0; defaults to 1.0.
instructionsstringNoOptional 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.

FieldTypeDescription
audio_urlstringTemporary signed MP3 download URL.
expires_atstringISO 8601 expiration time for the download URL (24 hours after generation).
durationnumber or nullAudio duration in seconds, when available.
characters_usednumberCharacters charged to quota, including the cloned-voice multiplier when applicable.
formatstringOutput format, mp3.
request_idstringIdentifier for this request; it does not make retries idempotent or recover a result.
generation_outcomestringsucceeded for this response.
quota_statusstringcharged 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.