API Documentation for Cloud Text-to-Speech Generation

By CoreVoice editorial team · Updated 2026-11-18

This guide shows HR and L&D teams how to integrate CoreVoice’s text-to-speech API into their training workflows. You will learn to generate clear audio files from onboarding scripts, e-learning modules, and policy documents using standard HTTP requests or the OpenAI SDK. The documentation covers authentication, voice selection, and formatting options tailored for corporate use.

We provide concrete examples for generating speech, managing rate limits, and handling long texts by splitting and joining audio segments. All requests follow a simple JSON structure, making it easy to automate voiceover production at scale without managing complex infrastructure. Use this reference to build reliable, consistent audio assets for your large teams.

API Documentation for Cloud Text-to-Speech Generation

Frequently asked questions

What is the base URL for the API?

The base URL is https://api.playk1k.com/v1. You can use the official OpenAI SDKs by changing the base_url to this endpoint. This allows you to integrate our text-to-speech API directly into your existing workflows using familiar SDK structures and methods.

Which SDKs are compatible?

The API follows the same request shape as the OpenAI speech endpoint. Therefore, the official OpenAI SDKs work perfectly by simply changing the base_url to https://api.playk1k.com/v1. You can also use plain HTTP requests if you prefer not to use an SDK.

How do I set the voice?

Include the voice parameter in your JSON body with one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice has a distinct tone, from warm narration to deep documentary styles. You can select a fit for your training content.

Can I change the speed?

Yes, you can adjust the speed between 0.25 and 4.0. This allows you to slow down complex instructions or speed up repetitive onboarding scripts. The speed parameter is part of the standard request body, giving you precise control over the audio pacing.

What is the character limit?

Each request supports up to 4096 characters of input text. For longer training manuals, split your text into parts of this size and join the resulting audio files. This ensures consistent quality and manageable processing times for each segment of your content.

How do I handle errors?

If synthesis fails, the charge is returned in full. Failed requests are free, so you can retry without worrying about extra costs. Check the response status code to determine if the request succeeded or failed, and handle retries accordingly in your application logic.

What formats are supported?

You can choose from mp3, wav, opus, flac, or pcm formats. Select the format that suits your LMS or audio player. The response returns the audio file directly, allowing you to store or stream it immediately after generation.

Is the API synchronous?

The API processes requests sequentially, meaning they are handled one after another. While typically fast, requests may wait in a queue under load. You receive the audio file in the response once generation is complete, rather than receiving partial audio streams.

Do I need to install extra libraries?

No, you do not need extra libraries specific to CoreVoice. You can use the official OpenAI SDKs or standard HTTP libraries. Just update the base_url to our API endpoint. This keeps your dependencies minimal and compatible with your existing tech stack.

How do I authenticate requests?

Include your API key in the Authorization header as a Bearer token. The format is 'Authorization: Bearer tts-...'. You can generate or rotate your key from your account dashboard. Each account has one active key at a time.

What happens if I exceed rate limits?

The limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a 10 requests per minute limit. You can monitor your usage and rate limits via the dashboard to plan your volume.

Can I use the same key for multiple projects?

Yes, a single active key can be used across multiple projects. However, all projects share the same rate limit and character count. If you need higher throughput, consider issuing a new key, which will immediately invalidate the old one.

How do I test the API?

Use the ready curl example provided on your dashboard. You can also use the official OpenAI SDKs with the adjusted base_url. Start with short texts to verify voice selection and format output before integrating into your main training content pipeline.

Where can I find the voices list?

Send a GET request to /v1/voices to retrieve the full list of available voices, languages, formats, and prices. This endpoint provides all the details you need to select the right voice for your specific HR and L&D use cases.

First request

curl

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

Getting your API key

Sound wave illustration for: Getting your API key

CoreVoice provides a reliable API for HR and L&D teams to generate audio from text. Access requires a unique API key, which you can obtain by creating an account on our site.

Sign up on the site

Visit https://playk1k.com/get-api-key/ to create your account. You can register using Google for immediate access or use an email and password. Google sign-ups receive a $0.50 trial credit valid for 7 days, while email accounts start without trial credit.

Find your key in the dashboard

After signing up, your dashboard displays your active API key starting with 'tts-'. This key authenticates your requests to the API endpoint. You can generate a new key at any time, which immediately invalidates the previous one.

Secure your key

Treat your API key like a password. It allows access to your account and billing. Since only one key is active at a time, rotating keys is a simple way to maintain security without service interruption.

  • One active key per account
  • New keys invalidate old ones instantly
  • Use environment variables in your scripts

First request with cURL

Sound wave illustration for: First request with cURL

To generate speech, send a POST request to the speech endpoint with your Bearer token. The API returns an audio file directly in the response body, allowing you to save it to your LMS.

This method works for any client that supports standard HTTP requests. Use the curl example below to test your integration quickly.

Basic JSON body

Send a JSON object containing the text, model, and voice. The endpoint accepts up to 4096 characters per request. Spaces and punctuation count toward the limit.

  • model: tts-1 or tts-1-hd
  • input: your training text
  • voice: e.g., aria or atlas
  • response_format: mp3, wav, opus, flac, or pcm

Required fields

You must provide the model, input text, and voice. The authorization header is mandatory. Language is optional but recommended for non-English text to ensure correct pronunciation.

  • Authorization: Bearer tts-your-api-key
  • model: string
  • input: string
  • voice: string

Response handling

A successful response contains the audio file bytes. Failed requests are free and return an error JSON. Save the output file with the specified format extension.

First request with cURL

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

Use the official OpenAI SDK for Python or Node.js to integrate CoreVoice into your training content pipelines. This approach allows your L&D team to leverage familiar code structures while routing requests through our API.

Configure the client to point to our endpoint by updating the base URL. This simple change enables standard speech generation methods without requiring a custom wrapper or additional dependencies.

Send your text payload using the standard speech method. The SDK handles the JSON serialization and response parsing, returning audio files directly to your application for immediate playback or storage.

Install the SDK

Install the latest version of the OpenAI SDK for your preferred language. For Python, run pip install openai. For Node.js, use npm install openai. Ensure your environment has the required runtime version installed.

  • Python: pip install openai
  • Node.js: npm install openai

Set base_url

Initialize the client with your API key and set the base_url to https://api.playk1k.com/v1. This directs all requests to CoreVoice’s infrastructure while maintaining compatibility with standard OpenAI SDK methods.

Use your Bearer token from the dashboard. The key format starts with tts- and authenticates your account for each request.

  • base_url: https://api.playk1k.com/v1
  • Auth: Authorization: Bearer tts-...

Call the speech endpoint

Invoke the audio.speech.create() method with your model, input text, voice, and response_format. The SDK returns the audio file directly, which you can save to your LMS.

Handle responses efficiently. Failed requests return no charge, ensuring your training budget remains accurate even during network fluctuations.

  • model: tts-1 or tts-1-hd
  • input: your training text
  • voice: e.g., 'nova'
  • response_format: mp3 or wav

Available voices

Sound wave illustration for: Available voices

Choosing the right voice is essential for maintaining engagement in corporate training and onboarding materials. Our eight presets are designed to deliver clear, consistent narration that fits various learning styles, from instructional guides to conversational scripts.

Each voice is distinct, allowing HR teams to match tone to content type. Whether you need a calm instructor for compliance modules or an energetic narrator for promotional content, the API supports your specific L&D workflow.

Female voices: Aria, Nova, Luna, Sage

Aria offers a warm, clear narration style ideal for general training content. Nova provides a bright, upbeat tone suitable for engaging onboarding sequences. Luna brings a soft, storytelling quality perfect for detailed case studies. Sage delivers a calm, instructional voice for complex procedural guides.

  • Aria: warm, clear narrator
  • Nova: bright, upbeat
  • Luna: soft, storytelling
  • Sage: calm, instructional

Male voices: Felix, Milo, Atlas, Orion

Felix is energetic and well-suited for promotional or fast-paced updates. Milo offers a friendly, conversational tone for interactive learning. Atlas provides a neutral, news-like delivery for standard corporate communications. Orion features a deep, documentary style for serious or historical content.

  • Felix: energetic, promo
  • Milo: friendly, conversational
  • Atlas: neutral, news
  • Orion: deep, documentary

Voice characteristics

All voices are based on licensed recordings from LibriTTS-R (CC BY 4.0), originally sourced from LibriVox public-domain audiobook readings. Every generated file contains an inaudible watermark identifying it as synthetic speech, ensuring transparency in your media assets. These voices can speak any of the 23 supported languages, allowing for consistent branding across global teams.

Supported audio formats

Sound wave illustration for: Supported audio formats

The API supports multiple audio formats to suit different deployment needs. You can choose from MP3, WAV, Opus, or FLAC by setting the response_format field in your request. This flexibility allows you to optimize for file size, quality, or compatibility with your existing HR and L&D infrastructure.

MP3 for web players

MP3 is a common format for web-based audio players. It offers a good balance between file size and audio quality, making it ideal for embedding training videos or audio modules in your LMS. Most modern browsers and media players support MP3 natively, ensuring smooth playback for employees accessing content on various devices.

  • Best for web-based audio players
  • Good balance of size and quality
  • Widely supported by browsers and LMS platforms

WAV for high quality

WAV provides uncompressed, high-fidelity audio. This format is suitable for professional voiceover production or archival purposes where audio integrity is critical. While the file sizes are larger, WAV ensures that the generated speech retains its original clarity without any lossy compression artifacts, which is useful for detailed instructional content.

  • Uncompressed, high-fidelity audio
  • Ideal for archival or professional production
  • Larger file sizes than MP3

FLAC and Opus options

FLAC and Opus offer lossless and lossy compression options, respectively. FLAC preserves full audio quality with smaller file sizes than WAV, while Opus provides efficient compression suitable for low-bandwidth environments. These formats are useful if you need to optimize storage or bandwidth without sacrificing too much quality.

  • FLAC: Lossless compression, smaller than WAV
  • Opus: Efficient lossy compression for streaming
  • Useful for optimizing storage or bandwidth
Supported audio formats

Language and speed settings

Sound wave illustration for: Language and speed settings

Precise language control ensures your training modules sound natural for global teams. While the API guesses the language from the script, explicitly setting the language field prevents misinterpretation, especially for non-English Latin-script text.

Speed adjustment lets you tailor narration to the content’s complexity. Slower rates aid comprehension for dense HR policies, while faster rates keep engaging e-learning modules concise without sacrificing clarity.

Set ISO language code

Pass the language parameter with an ISO 639-1 code (e.g., de, fr, es) to force a specific voice output. This is essential when your input text uses a Latin script but is not English, ensuring the model applies the correct phonetic rules.

  • Supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
  • Voices are multilingual; any voice can speak any supported language.

Adjust speed 0.25–4.0

The speed parameter accepts values from 0.25 to 4.0. Use lower speeds (0.5–0.8) for detailed onboarding scripts or compliance training where listeners need time to process information. Higher speeds (1.5–2.0) work well for quick updates or repetitive drill content.

  • Default speed is 1.0.
  • Speed changes do not affect the character count billing.

Auto-detection defaults

If you omit the language field, the API guesses the language based on the script. Latin script text defaults to English. For mixed-language content or less common Latin scripts, always specify the language to avoid incorrect pronunciation.

Rate limits and errors

Sound wave illustration for: Rate limits and errors

The API enforces strict rate limits to ensure stability for high-volume HR training deployments. Each API key is allowed a maximum of 60 requests per minute. This cap applies to all speech generation endpoints simultaneously.

60 requests per minute

Once your account is funded, you can send up to 60 requests every 60 seconds. If you exceed this limit, the API returns a 429 Too Many Requests error. Implement exponential backoff in your integration to handle retries gracefully during peak training module generation.

10 requests before top-up

New accounts start with a restricted limit of 10 requests per minute. This applies even if you have sufficient balance. You must complete a top-up via USDT (TRC-20) to unlock the full 60 requests/minute capacity. This ensures reliable delivery for critical onboarding audio.

Common error codes

We return standard HTTP status codes to help you debug integration issues quickly. Failed synthesis requests are free, so a 5xx error does not consume your character balance. Always check the response body for specific error messages regarding invalid voices or model issues.

  • 400 Bad Request: Invalid JSON body or missing required fields like 'model' or 'voice'.
  • 401 Unauthorized: Invalid or expired API key. Check your dashboard for the correct key.
  • 402 Payment Required: Insufficient balance. Top up via TRC-20 USDT to continue.
  • 429 Too Many Requests: Rate limit exceeded. Wait before retrying.
  • 500 Internal Server Error: Temporary processing issue. Retry with backoff; no charge incurred.
Rate limits and errors

Handling long texts

Sound wave illustration for: Handling long texts

When training manuals or onboarding scripts exceed 4,096 characters, you must split the text into smaller chunks. Each API request processes a single segment, so your application needs to handle the division logic before sending data to the endpoint.

4096 character limit per request

The API enforces a strict 4,096-character limit per input. Spaces and punctuation count toward this total. If your e-learning content is longer, send multiple requests sequentially.

Split and join strategy

Divide your source text into segments under the limit. Send each segment as a separate POST request. Ensure your application maintains the original order of the segments to preserve narrative flow.

Audio concatenation

The API returns individual audio files for each segment. Your system must concatenate these files in sequence to create the final training audio. This ensures a continuous listening experience for your HR team.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our collective growth depends on embracing new tools, sharing insights, and maintaining open communication across every department and role today.

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. curl documentation
  3. Node.js documentation
  4. openai-node on GitHub
  5. LibriTTS-R corpus (OpenSLR 141)
  6. FFmpeg documentation
  7. LibriVox public-domain audiobooks
  8. ISO 639 language codes
  9. IETF RFC 7845: Ogg Opus
  10. OpenAI API reference: create speech
  11. MDN: Web Speech API
  12. openai-python on GitHub

More on this site