REST API quickstart
This guide shows the REST API request sequence without making a live request. Generation can consume character credits. The API is in Beta, and an uncertain request must not be repeated automatically.
Before you start
You need an Acoust API key and an environment where you can keep it private. The API-key tab is currently hidden in the app. If you do not already have API-key access, contact Acoust support to ask about availability; do not use an MCP OAuth token as a REST API key. Keep the key in a local secret store or environment variable, never in a browser bundle, source control, or a support message.
The REST API base URL is https://api.acoust.io/v1. Requests use Authorization: Bearer YOUR_API_KEY and JSON for request bodies. See the REST API overview for errors and authentication details.
1. Find a voice
Copy the returned voice_id for the voice you want, along with one of its supported languages. This read request does not generate audio.
curl --get \
-H "Authorization: Bearer $ACOUST_API_KEY" \
--data-urlencode "language=en-US" \
"https://api.acoust.io/v1/voices"
Select a voice with a supported language. For a clone, use GET /v1/voices/cloned; only approved clones belonging to the authenticated account are listed. See voice catalog details.
2. Check the active quota
curl -H "Authorization: Bearer $ACOUST_API_KEY" \
"https://api.acoust.io/v1/usage"
The response reports TTS used, quota, and remaining plus a scope of personal or team. Generating speech with a cloned voice uses twice the input character count. See usage fields.
3. Request one clip
Only run a generation request when you intend to create audio and accept that it can consume quota. Replace VOICE_ID_FROM_CATALOG with a returned ID.
curl -X POST \
-H "Authorization: Bearer $ACOUST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Welcome to our weekly update.",
"voice_id": "VOICE_ID_FROM_CATALOG",
"language": "en-US"
}' \
"https://api.acoust.io/v1/tts/generate"
A successful response includes a temporary audio_url, expires_at, and generation and quota status. Save the MP3 before the URL expires (24 hours after generation). The API does not provide idempotency or result recovery.
4. Save the returned audio
Copy the complete audio_url from that successful response, keeping any query parameters, and replace AUDIO_URL_FROM_RESPONSE below. This downloads the existing result; it does not generate another clip.
curl --fail --location \
--output speech.mp3 \
"AUDIO_URL_FROM_RESPONSE"
After the download finishes successfully, open speech.mp3 from your current directory and listen to check the result. Treat the signed URL as private; do not include it in a support message or source control.
If the request errors or the result is missing
Do not automatically repeat a POST after an error, timeout, disconnect, or missing response. Audio may have been generated and quota consumed. If a response includes generation_outcome and quota_status, only quota_status: "refunded" confirms a refund; unknown means the outcome or charge could not be confirmed. Preserve the request_id and contact support if you need help investigating. A new generation is a separate request and may consume quota again.
For request fields and response examples, see Generate speech. For status codes, see REST API errors.