API Documentation for Text-to-Speech Integration

By VoxCove editorial team · Updated 2026-11-19

This guide details the integration steps for VoxCove’s text-to-speech API, designed specifically for advertising agencies generating high-volume radio spots. You will find precise specifications for the POST /v1/audio/speech endpoint, including required parameters for voice selection, audio format, and speed modulation. Use this reference to implement reliable, predictable audio synthesis into your production pipelines without guesswork.

Readers will learn how to authenticate with Bearer tokens, manage rate limits, and handle standard HTTP errors during bulk processing. The documentation covers request constraints, such as the 4096-character input limit, and explains language detection logic. All examples use standard HTTP requests compatible with the OpenAI SDK, ensuring straightforward integration for engineering teams building automated voiceover workflows.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.3phase.info/v1. You can use this endpoint to send POST requests for speech synthesis. The official OpenAI SDKs work by changing their base_url to this address. Use the /v1/audio/speech endpoint for generating audio files from your input text.

Does the API support WebSocket?

No, the API does not support WebSocket connections. It uses standard HTTP POST requests for all interactions. You send text and receive a complete audio file in the response. There is no real-time partial audio streaming available through this interface.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work by changing the base_url to https://api.3phase.info/v1. You must use your site-specific API key for authentication. The request shape matches the OpenAI speech endpoint exactly, allowing for easy integration into existing Python workflows.

What is the maximum text length?

The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, you must split the content into parts of up to 4096 characters and join the resulting audio files manually.

How do I get my API key?

Sign up on the /get-api-key/ page using Google or email. Accounts are per site. The page displays your active API key, balance, and usage statistics. You can issue a new key at any time, which stops the old one immediately.

Is the API compatible with cURL?

Yes, the API is fully compatible with cURL. The documentation page provides a ready cURL example for immediate testing. You can send POST requests with JSON bodies containing your model, input text, voice selection, and other parameters directly via command line.

Can I send audio in PCM format?

Yes, you can request PCM format by setting the response_format field to pcm. Other supported formats include mp3, wav, opus, and flac. The API returns the audio file directly in the response body in the specified format.

What happens if the server is down?

There is no SLA or uptime guarantee. Requests are processed sequentially, so under load they may wait in a queue. Failed requests are free, and the charge is returned in full if synthesis fails. Support is available via email only.

Do I need to install a specific SDK?

No, you do not need a specific SDK. Use the official OpenAI SDK or plain HTTP requests. We do not provide an official SDK of our own. The request shape matches the OpenAI speech endpoint, ensuring broad compatibility with existing tools.

Can I stream the audio response?

No, the API does not support streaming. You send a POST request and receive the complete audio file in the response. There is no WebSocket support or real-time partial audio delivery. Each request returns a finished audio file.

How do I handle long texts?

Split long texts into parts of up to 4096 characters. Send each part as a separate request to the /v1/audio/speech endpoint. Join the resulting audio files to create the final output. This ensures you stay within the character limit per request.

Is there a demo endpoint?

There is no separate demo endpoint. You can test the API immediately using the provided cURL example on the /get-api-key/ page. Use your API key to send a POST request to https://api.3phase.info/v1/audio/speech with sample text.

Can I specify the sample rate?

No, you cannot specify the sample rate. The API returns audio in the requested format (mp3, wav, opus, flac, pcm) with standard settings. You can control the speech speed between 0.25 and 4.0, but the audio sample rate is fixed by the engine.

Are there any version constraints?

The API uses version 1 of the endpoint path (/v1/). The models tts-1 and tts-1-hd are available. There are no specific version constraints for the SDKs, as long as they support the standard OpenAI speech endpoint structure. Use the latest stable versions.

First request

curl

curl https://api.3phase.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.3phase.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.3phase.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

Authentication relies on a single Bearer token passed in the Authorization header. Each account maintains one active key; issuing a new key immediately invalidates the previous one. This ensures that any compromised credential is instantly unusable, maintaining security for high-volume ad production pipelines.

Bearer token authorization

Bearer token authorization

Include the header Authorization: Bearer tts-<your-key> in every API request. The key is generated on the /get-api-key/ dashboard. It provides full access to the TTS endpoint and billing controls.

  • Format: Bearer tts-xxxxxxxxxxxxxxxxxxxxxxxx
  • Passed in HTTP header Authorization
  • Required for all POST and GET requests

Single active key per account

Single active key per account

Your account is tied to exactly one active API key at any time. This simplifies integration for agencies managing multiple sub-projects, as you can rotate keys without managing complex permission sets or user roles.

Key revocation on new issuance

When you generate a new key from the dashboard, the old key stops working immediately. There is no grace period. Ensure your production systems are updated before rotating keys to avoid synthesis failures in live radio spot deliveries.

Endpoint structure

Sound wave illustration for: Endpoint structure

The API exposes three primary endpoints for integration. The core synthesis endpoint accepts text payloads and returns audio files, while the metadata endpoints provide voice catalogs and model configurations. This structure mirrors standard OpenAI compatibility, allowing you to swap the base URL in existing SDKs without rewriting request logic.

POST /v1/audio/speech

Send a JSON body with your text, selected voice, and desired format to this endpoint. It returns the generated audio file directly in the response body. This is your primary route for converting radio scripts into audible assets.

GET /v1/voices

Retrieve the full list of available voice presets, supported languages, and output formats. Use this to dynamically populate your UI or configuration files before sending synthesis requests.

GET /v1/models

Fetch the list of available models, primarily tts-1 and tts-1-hd. Both models use the same engine and pricing, allowing you to switch quality levels without changing your voice selection logic.

Request parameters

Sound wave illustration for: Request parameters

The API accepts text input up to 4,096 characters per request. For longer radio scripts, split the text into chunks, generate each part, and join the audio files. Failed requests do not consume credit.

Choose between tts-1 and tts-1-hd models; both use the same engine and pricing. Select a voice preset that matches the tonal requirements of the spot, such as the calm instructional tone of Sage or the energetic promo style of Felix.

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

Select tts-1 or tts-1-hd in the model field. Both models use identical engines and pricing ($0.01 per 1,000 characters), allowing you to swap models without changing cost logic.

The input field accepts plain text strings. Ensure the total character count, including spaces and punctuation, does not exceed 4,096. Longer texts require client-side splitting and concatenation.

  • - tts-1: Standard engine
  • - tts-1-hd: Same engine, same price
  • - Max 4,096 characters per request
  • - Failed requests are free

Input text limit (4096 chars)

Each POST request processes a maximum of 4,096 characters. This limit applies to the input string length, including all spaces and punctuation marks.

For scripts exceeding this length, divide the text into sequential segments. Generate audio for each segment independently, then concatenate the resulting audio files on the client side.

Voice preset selection

Specify one of the eight available voices via the voice parameter. Each voice is tuned for specific advertising contexts, from the warm narration of Aria to the deep documentary tone of Orion.

All voices support all 23 listed languages. Use the language field to override automatic detection if the text script uses Latin script but is not English.

  • - aria: warm narrator
  • - nova: upbeat
  • - luna: storytelling
  • - sage: instructional
  • - felix: energetic promo
  • - milo: conversational
  • - atlas: neutral news
  • - orion: deep documentary

Response formats

Sound wave illustration for: Response formats

Synthesis returns raw audio binary, allowing direct file storage. Selecting the appropriate format depends on your delivery pipeline and playback environment.

MP3 output

MP3 is the default format, offering high compatibility with all major broadcasting standards and web players. It provides a good balance between file size and audio fidelity for radio spot production.

WAV output

WAV delivers uncompressed PCM audio, ideal for immediate ingestion into professional editing suites like Pro Tools or Adobe Audition. This format ensures no generation loss during post-production mixing.

OPUS and FLAC support

OPUS offers efficient compression for web delivery, while FLAC provides lossless compression for archival storage. Both formats are selectable via the response_format parameter.

  • OPUS: Best for web delivery
  • FLAC: Lossless archival quality

Speed control

Sound wave illustration for: Speed control

Speed control allows you to adjust the playback rate of synthesized speech from 0.25x to 4.0x, with a default of 1.0. This parameter directly influences the duration of the generated audio file, enabling precise timing adjustments for voiceover projects without requiring post-production editing.

Adjusting speed is critical for matching specific broadcast standards. Radio spots often require tighter pacing than natural conversation, while instructional content may benefit from slower delivery. The API processes requests sequentially, so queue latency remains dependent on current server load.

Range 0.25 to 4.0

The speed parameter accepts a float value between 0.25 and 4.0. Values outside this range will result in a 400 Bad Request error. The engine maintains voice quality and intonation across this entire range, ensuring the output remains natural even at extreme speeds.

  • Minimum: 0.25x (half speed) for slow, deliberate narration
  • Maximum: 4.0x (four times speed) for rapid announcements
  • Default: 1.0 (normal pace)
  • Accepts decimal values (e.g., 1.5) for fine-tuning

Default speed setting

If the speed field is omitted from the request JSON, the API defaults to 1.0. This ensures consistent output for standard voiceovers where no specific timing adjustment is needed. Using the default value simplifies integration for initial testing and standard-length radio spots.

Adjusting for radio pacing

For advertising agencies, precise timing is often mandatory. A 30-second spot may require exactly 60 words at normal pace. If the script runs long, increase the speed slightly (e.g., 1.1x) to fit the slot. Conversely, for emphasis-heavy reads, slowing to 0.9x can add weight without changing the word count. Note that character counts remain unchanged regardless of speed; billing is based on input text length, not audio duration.

Speed control

Language handling

Sound wave illustration for: Language handling

The API automatically detects the language of your input text based on the character script. If you send Latin script text without specifying a language, the system defaults to English. This works for simple cases but may misidentify mixed scripts or less common Latin-based languages.

For precise control, you can override the detection by providing a two-letter ISO language code in the request body. This ensures correct phonetic processing regardless of the input script, which is critical for consistent radio spot quality across diverse markets.

Automatic language detection

The engine analyzes the Unicode character set of your input to determine the primary language. This works reliably for distinct scripts like Cyrillic, Han, or Kana. For Latin script, it assumes English unless overridden.

  • Detects script type automatically
  • Works for all 23 supported languages
  • No additional configuration needed

ISO code override

Include the language field in your JSON payload with a valid ISO 639-1 code. This forces the engine to use the specified voice profile, ensuring accurate accent and pronunciation even if the script is ambiguous. Example: "language": "fr" for French.

  • Use two-letter ISO codes
  • Overrides automatic detection
  • Ensures consistent voice output

Default English for Latin script

If you send Latin text without a language parameter, the API assumes English. This is safe for English content but may produce incorrect accents for other Latin-based languages like Spanish, German, or Italian. Always specify language for non-English Latin text.

  • Default: English
  • Applies to Latin script only
  • Set language for other languages

Rate limits

Sound wave illustration for: Rate limits

The API enforces a strict rate limit of 60 requests per minute per key. This ceiling applies uniformly across all requests, ensuring predictable throughput for high-volume radio spot generation where multiple audio files may be generated concurrently. Exceeding this limit triggers a 429 Too Many Requests error.

New accounts start with a lower threshold of 10 requests per minute until the first top-up is processed. This allows agencies to test integration stability before committing to full-scale production loads. Once the first USDT transfer is confirmed, the limit automatically increases to the standard 60 RPM.

60 requests per minute

The standard rate limit allows 60 requests per minute. Each request counts toward this total, regardless of text length or voice selection. Agencies producing multiple radio spots simultaneously should monitor their usage to avoid hitting this cap during peak production hours.

  • Limit: 60 requests/minute per key
  • Applies to all request types

10 requests before first top-up

New accounts begin with a reduced limit of 10 requests per minute. This threshold remains active until the first top-up is successfully processed on the TRON network. Once the balance is credited, the limit automatically increases to 60 requests per minute.

  • Initial limit: 10 requests/minute
  • Increases after first top-up
  • No manual upgrade required

Queue behavior under load

Requests are processed sequentially. Under heavy load, requests may wait in a queue before synthesis begins. This ensures fair distribution of resources but may result in slightly longer generation times for short phrases. Long texts are split into parts, further adding to the queue time for large projects.

  • Sequential processing
  • Queuing under high load
  • Predictable timing for short texts

Error handling

Sound wave illustration for: Error handling

Errors return standard HTTP codes with JSON details. Failed synthesis charges are refunded automatically, ensuring you only pay for delivered audio. This protects your budget during pipeline debugging or voice selection phases.

400 Bad Request

Indicates invalid parameters. Check your request body for missing fields, unsupported formats, or text exceeding the 4096-character limit per segment. Verify that the voice ID exists in the /v1/voices list.

  • Ensure input text is UTF-8 encoded.
  • Confirm response_format is one of: mp3, wav, opus, flac, pcm.
  • Check that speed is between 0.25 and 4.0.

401 Unauthorized

Your Bearer token is missing, invalid, or expired. Regenerate your key from the /get-api-key/ dashboard if the current one stops working after issuing a new one. Include the header: Authorization: Bearer tts-...

429 Too Many Requests

You have exceeded the rate limit of 60 requests per minute. New accounts start with a 10 requests/minute limit until the first top-up. Requests queue under load; wait and retry with exponential backoff.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Each voice is derived from licensed recordings, providing a consistent baseline for quality.

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. W3C WAI: making audio and video accessible
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. MDN: Web Speech API
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. ISO 639 language codes
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. Node.js documentation
  11. TRON developer hub: TRC-20
  12. OpenAI API reference: create speech

More on this site