API Documentation: Integrate Text-to-Speech in Minutes

By VoiceCoda editorial team · Updated 2026-11-19

This documentation guides indie developers and freelancers through integrating our text-to-speech API. You will find exact specifications for endpoints, parameters, and authentication to calculate costs and build prototypes without hidden fees or complex enterprise contracts.

The guide covers OpenAI-compatible integration, allowing you to reuse existing SDKs by simply changing the base URL. We provide concrete curl examples, rate limit details, and error handling strategies to ensure reliable audio generation in production environments.

API Documentation: Integrate Text-to-Speech in Minutes

Frequently asked questions

How do I authenticate my requests?

Include an Authorization: Bearer tts-... header with your API key in every request. You can generate or rotate your key from the /get-api-key/ dashboard. Each account holds one active key; issuing a new one immediately invalidates the previous one.

Can I use the Python OpenAI SDK?

Yes. The API uses the same request shape as OpenAI’s speech endpoint. Configure your OpenAI SDK’s base_url to https://api.crn77.info/v1 and provide your site-specific key.

What is the maximum input length?

The input field supports up to 4096 characters per request. For longer texts, split your content into chunks of this size, generate audio for each part, and join the resulting audio files manually.

Does the API support streaming audio?

No, the API does not support streaming, WebSocket connections, or real-time partial audio. You receive the complete audio file in the response body after synthesis finishes. Use standard HTTP requests to fetch the file.

How do I handle rate limit errors?

The limit is 60 requests per minute per key (10 before the first top-up). If you exceed this, wait or implement exponential backoff. Requests are processed sequentially, so high load may also cause queuing delays.

Is JSON the only request format?

Yes, the API expects a JSON body for the POST request. You can send this via any HTTP client or SDK. The body must include model, input, voice, and optionally response_format, speed, and language.

Can I specify a language explicitly?

Yes, use the optional language field with an ISO code. If omitted, the system guesses the language from the script (defaulting to English for Latin text). Explicitly setting it ensures accuracy for non-English Latin-script content.

What happens if the API is slow?

Requests are processed sequentially, so under load, your request may wait in a queue. Typical speed is roughly real-time (25 characters per second), but short phrases may take a few seconds due to initialization overhead.

Do I need to install a specific SDK?

No, there is no official custom SDK. You can use the OpenAI SDK, plain HTTP libraries, or any tool that can send JSON POST requests. The endpoint is compatible with standard OpenAI request structures.

How do I detect the end of audio?

The API returns the complete audio file in the response body. There is no streaming or partial data. Once the HTTP response completes, you have the full audio file ready for playback or storage.

Is the API key reusable?

Yes, your API key remains active until you issue a new one. You can rotate keys at any time from your dashboard. When a new key is issued, the old one stops working immediately.

Can I use the same key on multiple servers?

Yes, you can use the same key across multiple servers or environments. The rate limit of 60 requests per minute applies per key, so distribute your traffic accordingly.

What is the response time for short texts?

Short phrases typically take a few seconds to generate. This includes processing time and potential queue delays if the server is under load. Longer texts process at roughly real-time speed, about 25 characters per second.

Are there any required headers?

Yes, you must include the Authorization: Bearer tts-... header with your API key. The request body must be JSON. No other headers are strictly required, but standard content-type headers are recommended for your HTTP client.

First request

curl

curl https://api.crn77.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.crn77.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.crn77.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: Authentication

Include your API key in the Authorization header as a Bearer token. This single key authenticates all requests to the https://api.crn77.info/v1 endpoint.

Bearer token header

Bearer token header

Pass your key using Authorization: Bearer tts-.... Ensure the header is included in every request to verify your account and deduct usage from your balance.

One active key per account

One active key per account

Each account maintains exactly one active key. Issuing a new key immediately invalidates the previous one, ensuring a single point of access for your integration.

Revoke keys instantly

Generate a new key from your dashboard to effectively revoke the old one. The transition is immediate, allowing you to rotate credentials without service interruption.

Endpoints Overview

Sound wave illustration for: Endpoints Overview

The API provides three primary endpoints for generating audio and managing resources. The core speech synthesis endpoint accepts text and configuration parameters to return an audio file. Two auxiliary endpoints allow you to retrieve available voice presets and model information without consuming credit.

POST /v1/audio/speech

This is the main endpoint for converting text to audio. Send a JSON body with model, input, and voice to receive an audio file. The request shape matches the OpenAI speech endpoint, allowing direct use of official SDKs.

  • Accepts text up to 4096 characters
  • Returns audio in MP3, WAV, OPUS, FLAC, or PCM
  • Supports speed adjustment from 0.25x to 4.0x

GET /v1/voices

Retrieve a list of all available voice presets and their metadata. This endpoint helps you verify which voices support specific languages or formats before making synthesis requests. It returns details for all eight presets: aria, nova, luna, sage, felix, milo, atlas, and orion.

GET /v1/models

Fetch the current list of available models. Currently, this returns tts-1 and tts-1-hd, which share the same engine and pricing. Use this to verify model availability and ensure your integration uses the correct model identifiers.

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts a JSON payload containing the text to synthesize. You must specify the model (tts-1 or tts-1-hd), the input text, and the voice preset. The language field is optional; if omitted, the system guesses the language from the script, defaulting to English for Latin text.

Model selection (tts-1, tts-1-hd)

Both tts-1 and tts-1-hd use the same engine and pricing. Choose based on your latency requirements rather than quality differences, as the engine and pricing are identical for both models.

Input text (max 4096 chars)

The input field accepts up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of this size and join the resulting audio files in your application logic.

Voice preset selection

Select one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Any voice can speak any of the 23 supported languages. If the text is in a non-English Latin script, explicitly set the language parameter to ensure correct pronunciation.

  • Female voices: aria, nova, luna, sage
  • Male voices: felix, milo, atlas, orion
  • Supports 23 languages including English, German, Japanese, Hindi, Arabic, Chinese, French, Spanish, and more.

Response Formats

Sound wave illustration for: Response Formats

The API returns audio as binary data in the response body. You can choose the output format via the response_format parameter. Supported formats include MP3, WAV, OPUS, FLAC, and PCM. This flexibility allows you to optimize storage and bandwidth based on your specific integration needs.

MP3 output

MP3 is a widely supported format. It offers a good balance between file size and audio quality. Use this format for web players and general distribution where file size matters.

WAV output

WAV provides uncompressed audio. Choose this format if you need lossless audio for editing or archival purposes. Note that WAV files are significantly larger than MP3s, which may impact storage and transfer costs.

OPUS, FLAC, PCM support

OPUS offers efficient compression with good quality, ideal for low-bandwidth environments. FLAC provides lossless compression. PCM returns raw, uncompressed audio data, useful for direct audio processing pipelines.

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a hard limit of 60 requests per minute per key. This ceiling applies uniformly regardless of text length or voice model. If you exceed this threshold, subsequent requests will fail with a 429 status code until the window resets.

Before your first top-up, the limit is reduced to 10 requests per minute. This lower tier applies during the free trial phase or if your account balance is zero. Once you add credit via USDT, the full 60 req/min limit is restored immediately.

60 requests per minute

The standard rate limit is 60 requests per minute for each active API key. This limit is calculated per key, so using multiple keys linearly increases your throughput. The limit resets every 60 seconds based on a sliding window.

  • Limit: 60 requests/minute per key
  • Applies to all models and voices
  • Calculated per API key

10 requests before first top-up

New accounts or those without a positive balance operate under a reduced limit of 10 requests per minute. This ensures fair usage during the free trial period. The limit automatically upgrades to 60 req/min once your first USDT top-up is confirmed and credited.

  • Trial accounts: 10 req/min
  • Auto-upgrades after first top-up
  • No manual verification needed

Queue handling under load

Requests are processed sequentially within the rate limit window. If you send bursts of requests, they are queued and processed one after another. Longer texts may take a few seconds to generate, so plan your batch sizes accordingly to avoid unnecessary latency.

  • Requests are queued sequentially
  • Processing time depends on text length
  • No parallel streaming available
Rate Limits

Error Codes

Sound wave illustration for: Error Codes

The API returns specific HTTP status codes to help you handle failures gracefully. Failed synthesis requests are free, so you won’t be charged if the engine rejects your input or runs out of quota mid-process. Always check the response body for detailed error messages to debug issues quickly.

Understanding these codes ensures your integration remains robust during high-volume usage or when configuration parameters are incorrect.

400 Bad Request

Returned when the request body is malformed or contains invalid values, such as an unsupported voice or text exceeding 4096 characters.

Check your JSON structure and ensure the input field does not exceed the character limit. Verify that the voice and model fields match the available presets and models listed in the API documentation.

  • Invalid JSON structure
  • Text exceeds 4096 characters
  • Unknown voice ID
  • Invalid speed value (must be 0.25–4.0)

401 Unauthorized

Indicates that the Authorization header is missing or contains an invalid API key. Ensure you are using the correct Bearer token generated from your account dashboard.

If you recently rotated your key, the old one becomes invalid immediately. Update your integration to use the new key to restore access.

  • Missing Authorization header
  • Invalid API key
  • Key expired or revoked

429 Too Many Requests

Triggered when you exceed the rate limit of 60 requests per minute per key. New accounts start with a limit of 10 requests per minute until the first top-up.

Requests may also queue under load, causing delays. Implement exponential backoff in your client to handle temporary throttling without dropping requests.

  • Exceeded 60 requests/minute
  • New account limit (10 req/min)
  • Temporary throttling due to high load

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

Integrate VoiceCoda’s text-to-speech engine into your existing projects by simply redirecting the OpenAI SDK’s base URL to https://api.crn77.info/v1. This allows you to leverage familiar libraries without rewriting your integration logic, ensuring a smooth transition for indie developers and freelancers who already use OpenAI’s client packages.

Change base_url to api.crn77.info

Update your SDK configuration to point to our endpoint. For example, in Python, set base_url="https://api.crn77.info/v1". This directs all API calls to our infrastructure while maintaining standard authentication via your tts-... bearer token.

Use official OpenAI SDKs

Leverage the official OpenAI SDKs (Python, Node.js, etc.) by changing the base URL. The SDK handles serialization, retries, and response parsing, reducing boilerplate code.

Same request shape as OpenAI

The request payload mirrors the OpenAI speech endpoint structure. Use fields like model, input, voice, response_format, and speed exactly as documented. This consistency means you can swap providers or test different engines with minimal code changes.

  • Supports tts-1 and tts-1-hd models
  • Accepts standard parameters: input, voice, response_format
  • No custom SDK required; use existing tools

Curl Example

Sound wave illustration for: Curl Example

This section provides ready-to-use curl commands for immediate testing. It covers standard text-to-speech synthesis, configuration of voice and output format, and proper handling of the binary audio response in your terminal.

All endpoints use the base URL https://api.crn77.info/v1. Replace YOUR_API_KEY with your actual token from /get-api-key/.

Basic speech generation

Generate audio with the nova voice in MP3 format. The input text is limited to 4096 characters.

```bash curl -X POST https://api.crn77.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3 ```

Specifying voice and format

Use any of the 8 preset voices and select from mp3, wav, opus, flac, or pcm. Set the speed between 0.25 and 4.0.

```bash curl -X POST https://api.crn77.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "input": "Custom narration", "voice": "atlas", "response_format": "wav", "speed": 1.5}' \ -o output.wav ```

Handling binary response

The API returns binary audio data. Redirect the output to a file using the -o flag. For debugging, omit -o to view raw bytes.

```bash curl -X POST https://api.crn77.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Debug test", "voice": "milo"}' \ -o debug_audio.opus ```

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Spaces between words and punctuation marks like commas, periods, and question marks are included in the character count.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. FFmpeg documentation
  3. ISO 639 language codes
  4. openai-python on GitHub
  5. MDN: Web Speech API
  6. curl documentation
  7. Node.js documentation
  8. IETF RFC 7845: Ogg Opus
  9. Creative Commons Attribution 4.0
  10. LibriVox public-domain audiobooks
  11. OpenAI API reference: create speech
  12. LibriTTS-R paper (arXiv 2305.18802)

More on this site