Integrate Text-to-Speech into Your Platform with Our API

By VocalGuide editorial team · Updated 2026-11-19

This guide provides the technical reference you need to integrate VocalGuide’s text-to-speech API into your corporate learning management systems or HR platforms. We cover authentication, endpoint structures, and parameter configurations so your team can generate consistent, multilingual audio for e-learning modules without relying on expensive studio recordings.

You will find clear examples for integrating with the OpenAI SDK, handling errors, and managing rate limits. Whether you are building a custom dashboard or automating curriculum updates, this documentation ensures you can scale voiceover production efficiently using our reliable, compliant synthetic voices.

...

...

Integrate Text-to-Speech into Your Platform with Our API

Frequently asked questions

What is the character limit per request?

Each request accepts up to 4096 characters of input text. For longer texts, you must split the content into parts of this size and join the resulting audio files. Spaces and punctuation count toward this limit. This ensures consistent processing performance across all supported languages and voices without exceeding the single-request boundary.

Which audio formats are supported?

The API supports five output formats: mp3, wav, opus, flac, and pcm. You specify the desired format using the response_format field in your JSON request body. This allows you to choose between compressed audio for efficient storage or uncompressed formats for high-fidelity playback in your e-learning modules.

How many voices are available?

There are eight voice presets available, including four female and four male options. These include Aria, Nova, Luna, and Sage, and Felix, Milo, Atlas, and Orion. All voices can speak any of the 23 supported languages, providing flexibility for diverse training content.

Does the API support multiple languages?

Yes, the API supports 23 languages, including English, Spanish, German, French, Japanese, and Arabic. Any voice can speak any of these languages. If the language field is omitted, the system guesses the language from the script, defaulting to English for Latin text, so you should explicitly set it for non-English content.

What are the rate limits?

You are limited to 60 requests per minute per API key. Before your first top-up, this limit is reduced to 10 requests per minute. Requests are processed sequentially, so under load, a request may wait in a queue. Failed requests are free.

How is pricing calculated?

Pricing is $10 per 1 million characters, or $0.01 per 1,000 characters. Spaces and punctuation count as characters. Failed requests are free, with charges returned in full if synthesis fails. There are no monthly plans, seats, or minimum spends, allowing you to pay only for the audio you successfully generate.

How do I top up my balance?

Top-ups are made via USDT on the TRON network (TRC-20) only. The minimum top-up amount is $5. Credits are automatically added to your balance within minutes after the transfer is confirmed. There are no credit cards, PayPal, or subscriptions; your balance does not expire, and you can issue a new key at any time.

Is there a free trial?

Yes. Signing in with Google provides a $0.50 trial credit valid for 7 days, covering approximately 50,000 characters. Email-based accounts start without this credit. Any of the 8 voices can speak any of the 23 listed languages, eliminating the need for multiple voice models. This allows you to test the API’s quality and integration before committing to a top-up via the TRON network.

First request

curl

curl https://api.yanyabet.net/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.yanyabet.net/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.yanyabet.net/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 active API key per account, passed via the Authorization: Bearer <key> header. This key grants access to all endpoints, including voice lists and model details, ensuring a straightforward integration for HR platforms generating training audio.

Bearer token format

Bearer token format

Include the header Authorization: Bearer tts-... in every request. The key format is consistent across all endpoints, allowing you to use standard HTTP libraries or the OpenAI SDK by simply adjusting the base URL to https://api.yanyabet.net/v1.

API key management

Each account holds one active key, visible on the /get-api-key/ dashboard alongside your balance and usage stats. This key identifies your account and tracks character consumption against your prepaid USDT balance.

Key rotation

You can issue a new key at any time via the dashboard. The old key stops working immediately upon generation of the new one, allowing zero-downtime rotation without manual invalidation steps.

Endpoint structure

Sound wave illustration for: Endpoint structure

The API exposes three primary endpoints for generating and managing audio assets. The core synthesis endpoint accepts text payloads and returns audio files, while discovery endpoints allow you to list available voices and model configurations dynamically.

These endpoints follow a standard RESTful structure, making integration straightforward for HR platforms that need to batch-generate training modules or onboarding clips without hardcoding voice details.

POST /v1/audio/speech

This is the main endpoint for converting text into speech. Send a JSON payload with your input text, selected voice, and desired format to receive an audio file.

The request body mirrors the OpenAI speech endpoint structure, allowing you to use existing OpenAI SDK clients by simply adjusting the base URL to https://api.yanyabet.net/v1.

  • Accepts up to 4096 characters per request
  • Supports formats: mp3, wav, opus, flac, pcm
  • Returns audio data directly in the response body

GET /v1/voices

Retrieve a list of all available voice presets, their associated languages, and supported output formats. This helps your application dynamically populate voice selection dropdowns for end-users.

Each voice is a preset based on licensed recordings, ensuring consistent tone across your corporate training library.

  • Returns voice ID, name, gender, and available languages

GET /v1/models

Fetch the current list of available TTS models, including the standard tts-1 and high-definition tts-1-hd options. Use this to verify model availability before attempting synthesis.

This endpoint ensures your integration remains compatible even if model configurations change behind the scenes.

  • Lists model ID and display name
  • Indicates current status and availability

Request parameters

Sound wave illustration for: Request parameters

The API accepts plain text inputs up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer e-learning scripts, split the content into chunks and join the resulting audio files.

Input text limit

Each synthesis request handles a maximum of 4,096 characters. Exceeding this requires manual segmentation of the source material. Shorter phrases may take a few seconds to generate, while longer texts process at roughly real-time speed.

Voice selection

Choose from eight presets based on licensed recordings. Female voices include Aria, Nova, Luna, and Sage. Male options are Felix, Milo, Atlas, and Orion. Any voice supports all 23 languages; specify the language code if the script is not English.

  • Aria: warm, clear narrator
  • Nova: bright, upbeat
  • Luna: soft, storytelling
  • Sage: calm, instructional
  • Felix: energetic, promo
  • Milo: friendly, conversational
  • Atlas: neutral, news
  • Orion: deep, documentary

Speed control

Adjust playback speed between 0.25 and 4.0. This allows fine-tuning for training modules where clarity or pacing needs to be adjusted without re-recording. The default speed maintains natural cadence for most corporate content.

Response formats

Sound wave illustration for: Response formats

The API returns generated audio files in the format specified by the response_format parameter, allowing you to choose the optimal balance between file size and compatibility for your corporate learning platforms.

MP3 output

MP3 is the default and most widely supported format, ideal for embedding audio directly into HTML5 players or distributing via standard LMS systems. It offers a good balance between compression and quality for general narration tasks.

WAV support

WAV provides uncompressed, high-fidelity audio suitable for professional editing or archival purposes within your training workflow. Use this format when you need to process the voiceovers further in audio production software without generation loss.

Opus and FLAC options

Opus offers superior compression for smaller file sizes while maintaining quality, beneficial for bandwidth-constrained environments. FLAC provides lossless compression, preserving exact audio data while reducing storage footprint compared to uncompressed WAV.

OpenAI SDK integration

Sound wave illustration for: OpenAI SDK integration

Since the API mirrors the OpenAI speech endpoint structure, existing OpenAI SDKs can be reused by simply adjusting the base URL. This allows HR tech teams to integrate voice generation without learning a new client library or rewriting core request logic.

Base URL configuration

Set the base_url to https://api.yanyabet.net/v1 in your SDK configuration. This directs all requests to the VocalGuide endpoint while maintaining standard OpenAI compatibility.

Client initialization

Initialize the client using your standard Bearer token. Ensure the token begins with tts- and is passed in the Authorization header. The SDK handles authentication automatically once configured.

Method calls

Call the speech method with your text, voice preset, and desired format. The response returns the audio file directly, allowing immediate playback or storage for your e-learning modules.

OpenAI SDK integration

Error handling

Sound wave illustration for: Error handling

When synthesis fails, the charge is returned in full, ensuring you only pay for successful generations. This reliability is critical for automated HR training pipelines where consistent billing is required.

HTTP status codes

The API returns standard HTTP status codes to indicate success or failure. Use these codes to determine if a request should be retried or if it requires immediate attention from your engineering team.

Retry logic

Implement exponential backoff for transient errors. Since requests are processed sequentially, under load a request may wait in a queue before timing out. Failed requests do not consume your rate limit allowance and are free, so retrying on temporary failures is cost-effective.

Character limits

Each request accepts up to 4096 characters. Exceeding this limit results in an error. For longer training modules, split the text into parts of up to 4096 characters and join the resulting audio files in your post-processing step.

Rate limits

Sound wave illustration for: Rate limits

Your API key allows 60 requests per minute for standard operation, which is sufficient for most e-learning batch processing. This limit ensures stable audio generation during peak curriculum updates without overwhelming the synthesis engine.

60 requests per minute

Under normal conditions, you can send up to 60 synthesis requests within a one-minute window. This capacity supports scalable content delivery for corporate training modules where multiple voiceovers are generated simultaneously.

Initial 10 per minute

New accounts without a top-up start with a lower limit of 10 requests per minute. This restriction applies until you add credit to your balance, allowing you to test the API within the free trial or initial usage.

Quota reset

The rate limit resets every minute.

Curl example

Sound wave illustration for: Curl example

Below is a concrete example of how to generate audio using the VocalGuide API. This request demonstrates the standard JSON body structure required for synthesis, including model selection, voice preset, and input text constraints.

Basic request

Send a POST request to the speech endpoint with your Bearer token. The example below uses the standard "tts-1" model to convert a short training script into an MP3 file.

  • Endpoint: https://api.yanyabet.net/v1/audio/speech
  • Method: POST
  • Header: Authorization: Bearer YOUR_API_KEY

JSON body structure

The request body must include the model, input text (max 4096 characters), voice, and response_format. Ensure the text matches your target language or set the language code explicitly.

Audio response

The API returns the audio file directly in the response body with the specified MIME type. Failed requests are free.

faq [8]: [8 questions]

Sound wave illustration for: faq [8]: [8 questions]

Developers often ask about character limits and language support. Our API enforces a 4096-character limit per request, requiring text splitting for longer training modules. All 23 supported voices can speak any of the 23 listed languages, eliminating the need for multiple voice models.

Do voices support all 23 languages?

Yes. Any of the 8 voices can speak any of the 23 listed languages. If the language parameter is omitted, the system guesses from the script, defaulting to English for Latin text. Explicitly set the language for non-English Latin-script inputs to ensure accuracy.

What happens if a request fails?

Failed synthesis requests are free. If the engine cannot generate audio, the charge is returned in full. This ensures you only pay for successful audio files delivered to your platform.

Can I stream audio in real-time?

No. The API returns complete audio files after synthesis. There is no WebSocket or streaming endpoint. For long e-learning modules, split text into chunks under 4096 characters and join the resulting audio files on your end.

Is SSML or pronunciation control available?

No. We do not support SSML, phoneme dictionaries, or custom pronunciation lexicons. Voices follow standard pronunciation rules based on the input text and specified language.

How does key rotation work?

You can issue a new API key at any time. When a new key is generated, the old one stops working immediately. This allows for secure key management without downtime.

What are the rate limits?

New accounts start with 10 requests per minute. After the first top-up, the limit increases to 60 requests per minute. This handles typical e-learning content generation loads efficiently.

Do voices sound like real people?

Voices are based on licensed recordings from LibriVox public-domain audiobooks. Each generated file carries an inaudible watermark marking it as synthetic speech, ensuring transparency for compliance.

Can I clone my own voice?

No. We do not offer custom voice cloning or uploading of personal voice samples. You must choose from the 8 available presets: Aria, Nova, Luna, Sage, Felix, Milo, Atlas, or Orion.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. His impartial tone ensures clarity and neutrality when delivering regulatory information.

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. openai-python on GitHub
  3. OpenAI API reference: create speech
  4. ISO 639 language codes
  5. LibriVox public-domain audiobooks
  6. LibriTTS-R corpus (OpenSLR 141)
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. Tether (USDT)
  9. IETF RFC 7845: Ogg Opus
  10. Python documentation
  11. MDN: Web Speech API
  12. W3C WAI: making audio and video accessible

More on this site