Skip to main content

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.