API Documentation: Integration and Endpoints

By LingoCast editorial team · Updated 2026-11-19

This documentation provides the technical reference for the LingoCast TTS API, designed for game developers and content creators integrating NPC dialogue and in-game audio pipelines. You will find precise details on endpoints, parameters, and integration patterns to generate synthetic speech programmatically.

The guide covers authentication, request structures, and response handling. It includes concrete examples for the OpenAI SDK and standard HTTP clients, ensuring you can start generating audio files immediately with reliable, standard-compliant workflows tailored for development environments.

API Documentation: Integration and Endpoints

Frequently asked questions

How do I get an API key?

Sign up on the /get-api-key/ page using Google or email. Accounts are per site. The dashboard displays your active key, balance, trial status, characters left, and usage. You can issue a new key at any time; the previous one stops immediately.

What is the base URL?

The API base URL is https://api.vip0.info/v1. Use this for all requests, including the speech endpoint at /v1/audio/speech and the voices endpoint at /v1/voices. Ensure your Authorization header uses the Bearer token format with your specific key.

How do I use the OpenAI SDK?

The API matches the OpenAI speech endpoint shape. Update the OpenAI SDK's base_url to https://api.vip0.info/v1 and use your LingoCast key. This allows you to use official OpenAI SDKs directly without custom client implementations for standard speech generation.

What is the maximum text length?

Each request supports up to 4096 characters in the input field. For longer texts, split the content into parts of this size and join the resulting audio files. Spaces and punctuation count toward the character limit.

Can I change the speed?

Yes, the speed parameter accepts values between 0.25 and 4.0. This allows you to adjust the speaking rate for NPC dialogue or narration. The default speed is 1.0, but you can fine-tune it for specific audio pipeline needs.

Which voices are available?

Eight presets are available: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. These cover warm narrator, bright upbeat, soft storytelling, calm instructional, energetic promo, friendly conversational, neutral news, and deep documentary tones. Each voice can speak any of the 23 supported languages.

What happens if I exceed rate limits?

The limit is 60 requests per minute per key (10 before the first top-up). Exceeding this may cause requests to queue or fail. Failed requests are free, but successful ones incur charges. Monitor your usage via the dashboard.

How do I handle errors?

The API returns standard HTTP error codes. Failed synthesis requests are free, and charges are returned in full. Check the response body for details. Ensure your input text is under 4096 characters and your key is valid.

Is the response always JSON?

No. The /v1/audio/speech endpoint returns the audio file directly in the response body, formatted as requested (mp3, wav, opus, flac, or pcm). The /v1/voices endpoint returns JSON metadata. Use the correct endpoint for your data type.

Can I use custom models?

No custom models are offered. The API uses two fixed models: tts-1 and tts-1-hd. Both use the same engine and price. You select the model via the request body, but no voice cloning or custom training is available.

How do I rotate my API key?

Issue a new key from the /get-api-key/ dashboard page. The old key stops working immediately. This ensures secure access without downtime. You can generate a new key at any time to maintain security for your game audio pipelines.

What is the input format?

Send a POST request with a JSON body containing the text in the 'input' field, up to 4096 characters. Include the 'model', 'voice', and 'response_format'. The 'language' field is optional but recommended for non-English Latin script text.

First request

curl

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

Secure access to the LingoCast TTS API requires a valid API key issued to your account. Keys are generated on the /get-api-key/ dashboard and are tied to your specific site account. Use this key to authenticate every request sent to the API base.

Each account maintains one active key at a time. If you rotate or regenerate your key, the previous key becomes invalid immediately. This ensures that if a key is compromised, you can revoke access instantly without waiting for a renewal cycle.

API Key Format

API Key Format

API keys follow the prefix tts- followed by a unique alphanumeric string. You can view your current key and balance on the dashboard. Keep this string secure, as it provides full access to your voice generation credits.

  • Format: tts- followed by random alphanumeric characters
  • Scope: Single active key per account
  • Location: Viewed in the /get-api-key/ dashboard

Bearer Token

Bearer Token

Include your API key in the Authorization header of every request. Use the standard Bearer token scheme. Example: Authorization: Bearer tts-abc123.... This header is required for all endpoints, including speech generation and voice listing.

Ensure the token is passed correctly in your HTTP client. Misformatted headers will result in 401 Unauthorized errors, which do not consume your character balance.

  • Header: Authorization: Bearer <key>
  • Required for all requests
  • Does not consume credits on failure

Key Rotation

You can issue a new key at any time from your dashboard. Upon generation, the old key is deactivated instantly. This is useful for CI/CD pipelines or when rotating credentials in production environments.

Since only one key is active, ensure your application updates to the new key immediately after rotation to avoid service interruption.

  • New keys deactivate old ones instantly
  • No downtime during rotation if updated immediately
  • Available anytime from the dashboard

Speech Endpoint

Sound wave illustration for: Speech Endpoint

Send your text payload to the speech endpoint to receive synthesized audio. The API accepts standard JSON bodies, allowing you to integrate seamlessly into existing game engines or content pipelines without complex middleware.

This endpoint handles the core synthesis logic, converting your input characters into audio files. It supports the same request shape as the OpenAI speech endpoint, ensuring compatibility with existing client configurations when the base URL is changed.

POST Method

Use the HTTP POST method to submit synthesis requests. The endpoint URL is https://api.vip0.info/v1/audio/speech. Send your request body as application/json to initiate audio generation.

JSON Body Structure

Your request body must include the text to be spoken. You can specify the voice, response format, and speed. The input text is limited to 4096 characters per request.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string (max 4096 chars)
  • voice: one of the 8 available presets
  • response_format: mp3, wav, opus, flac, or pcm
  • speed: 0.25 to 4.0
  • language: optional ISO code

Response Format

The API returns the generated audio file directly in the response body. The format matches your specified response_format parameter, allowing immediate playback or storage in your game assets.

Every generated file carries an inaudible watermark that marks it as synthetic speech.

Parameters

Sound wave illustration for: Parameters

The API accepts plain text input up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer dialogues, split the text into chunks and concatenate the resulting audio files. The system processes requests sequentially, so under load, queueing may occur.

Select from eight distinct voice presets ranging from warm narrators to energetic promos. You may optionally specify a language code (e.g., 'en', 'es') to ensure correct pronunciation for Latin-script texts. If omitted, the system guesses the language, defaulting to English for Latin script.

Input Text

Send up to 4096 characters per request. Spaces and punctuation count. For longer lines, split and join audio.

Processing is sequential. Under load, requests may queue, affecting real-time responsiveness for rapid fire.

  • Max 4096 characters per request
  • Spaces and punctuation count
  • Split and join for longer texts

Voice Selection

Choose from eight licensed voices. Each voice supports all 23 supported languages. Set the 'voice' field to the preset name.

Optionally set 'language' to an ISO code (e.g., 'fr', 'ja'). Without it, Latin text defaults to English.

  • 8 preset voices available
  • Supports all 23 languages
  • Optional language ISO code

Speed Control

Adjust speech rate between 0.25x and 4.0x. This allows fine-tuning for NPC dialogue pacing or fast narration.

Standard speed is 1.0.

  • Range: 0.25 to 4.0
  • Fine-tune NPC pacing
  • Natural voice distortion

Models

Sound wave illustration for: Models

The API offers two model identifiers, "tts-1" and "tts-1-hd," which utilize the identical underlying synthesis engine. Both models support the same eight voice presets and handle text inputs up to 4096 characters per request.

There is no functional difference in voice quality or audio generation speed between the two options; they use the same engine and price. They share the same pricing tier, processing queue behavior, and supported output formats.

tts-1 Model

Identified as "tts-1" in the request payload, this model is the standard option for NPC dialogue and ambient voice lines.

It supports all eight voices (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) and processes requests at the standard rate of roughly real-time generation.

  • Model ID: tts-1
  • Pricing: $10 per 1 million characters
  • Input limit: 4096 characters

tts-1-hd Model

Identified as "tts-1-hd," this model uses the same engine and pricing structure as the standard model.

Selecting this identifier does not incur additional costs or provide higher audio fidelity compared to tts-1.

  • Model ID: tts-1-hd
  • Pricing: $10 per 1 million characters
  • Same engine as tts-1

Engine Differences

Both model identifiers route to the same synthesis engine, ensuring consistent voice characteristics and language support.

The primary distinction is purely the string identifier passed in the JSON body; audio output quality remains identical.

Response Formats

Sound wave illustration for: Response Formats

The API supports five standard audio formats, allowing you to choose the optimal balance between file size and quality for your game engine or audio pipeline. Each response returns the raw binary audio data directly in the HTTP response body, ready for immediate decoding or storage.

MP3 Output

MP3 is the default format, offering efficient compression suitable for most in-game dialogue assets. It ensures broad compatibility with existing audio middleware and reduces bandwidth usage during asset streaming.

  • Default output format
  • Optimal for general NPC dialogue

WAV Output

WAV provides uncompressed PCM audio, ideal for high-fidelity voice lines or when minimal decoding overhead is required. Use this when your engine prefers raw data without decoding overhead.

  • Uncompressed audio quality
  • Minimal decoding overhead

Opus and FLAC

Opus offers superior compression at low bitrates, while FLAC provides lossless compression for archival or master tracks. Both formats allow you to optimize storage without sacrificing audio integrity or introducing artifacts.

  • Opus: efficient low-bitrate compression
  • FLAC: lossless archival quality
Response Formats

Rate Limits

Sound wave illustration for: Rate Limits

Requests are processed sequentially, meaning synthesis happens one after another. Under heavy load, your requests may queue, so plan your pipeline accordingly. This ensures consistent quality without overloading the engine.

60 Requests Per Minute

You are limited to 60 requests per minute per API key. This applies to all synthesis attempts, regardless of text length or voice chosen. Exceeding this limit returns a 429 error.

Initial Limit

New accounts start with a lower limit of 10 requests per minute. This allows you to test the API without immediate throughput pressure. The limit increases automatically within minutes after topping up your balance.

Limit Increase

Top up your account with USDT (TRC-20) to increase your rate limit. The increase is credited automatically within minutes. This allows you to scale your NPC dialogue generation or audio pipeline as needed.

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate success or failure. A 200 OK response confirms the audio file was generated and is included in the response body. Any non-2xx code indicates an error, such as 401 for invalid authentication or 429 for rate limit exceedance.

Standard Error Codes

Use the HTTP status code to determine the issue. 400 errors indicate bad request syntax, while 401 errors mean your API key is invalid or expired. Check your request headers and ensure the key format is correct.

  • 400: Bad Request
  • 401: Unauthorized
  • 429: Too Many Requests

Failed Request Refund

If synthesis fails due to a server-side error, the charge is returned in full. You are only billed for successful audio generations. This ensures you pay only for usable NPC dialogue or content assets.

Validation Errors

Errors often arise from exceeding the 4096 character limit or using an invalid voice name. Ensure your text is split into chunks and that the voice ID matches one of the eight presets. Check the response body for specific details.

SDK Integration

Sound wave illustration for: SDK Integration

The API endpoint structure matches the OpenAI speech endpoint exactly, allowing you to use the official OpenAI SDK with minimal configuration. This compatibility means you can leverage existing client libraries without writing custom HTTP parsers or handling raw JSON serialization for your game’s audio pipeline.

Simply point the SDK’s base URL to our service and supply your LingoCast API key. This approach ensures consistent behavior across different languages and environments while keeping your integration code clean and maintainable for NPC dialogue generation.

OpenAI SDK

Use the standard OpenAI Python or Node.js client. It handles the request serialization and response parsing automatically, reducing boilerplate code in your game’s audio subsystem.

The SDK supports both sync and async modes, allowing you to queue voice lines without blocking your game’s main thread.

  • Compatible with OpenAI SDK versions 1.0.0+

Base URL Change

Override the default base URL to direct requests to the LingoCast API endpoint. This single change routes all speech synthesis calls through our infrastructure without modifying your core logic.

Ensure your base URL points to https://api.vip0.info/v1 to access the correct versioned endpoints for speech and voice retrieval.

Client Setup

Initialize the client with your API key in the authorization header. The key format is tts-... and should be passed as a Bearer token for every request.

Test the connection by sending a short sample text. If the request succeeds, your integration is ready for production NPC dialogue generation.

  • Key format: tts-...
  • Auth header: Bearer <key>

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Avoid these three frequent errors to ensure consistent voice generation and accurate billing.

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. LibriVox public-domain audiobooks
  3. curl documentation
  4. TRON developer hub: TRC-20
  5. Tether (USDT)
  6. W3C WAI: making audio and video accessible
  7. ISO 639 language codes
  8. OpenAI API reference: create speech
  9. openai-node on GitHub
  10. FFmpeg documentation
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Python documentation

More on this site