API Documentation: Quickstart and Integration

By SpeechCraft editorial team · Updated 2026-11-19

This guide helps mobile product teams integrate SpeechCraft’s text-to-speech API quickly. You will find the exact endpoints, parameters, and authentication steps needed to generate audio files from your app’s backend or client-side code. We focus on practical integration details, such as handling character limits and managing voice selection, so you can build reliable audio features without unnecessary complexity.

The documentation covers everything from setting up your Bearer token to understanding rate limits and response formats. You will learn how to control speech speed, handle language detection, and manage errors effectively. Whether you are generating short notifications or longer narrative content, this page provides the concrete examples and technical specifics you need to get started immediately.

API Documentation: Quickstart and Integration

Frequently asked questions

How do I get an API key?

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

What is the request format?

Send a POST request to https://api.playmk777.com/v1/audio/speech with a JSON body. Include the model, input text, voice, response_format, and optional speed or language. Authenticate with Authorization: Bearer tts-.... The structure matches the OpenAI speech endpoint exactly.

Can I use the OpenAI SDK?

Yes. The API uses the same request shape as OpenAI’s speech endpoint. Configure your SDK’s base_url to https://api.playmk777.com/v1 and use your site’s key. This allows you to use official OpenAI SDKs without modification for integration.

What models are available?

Two models exist: tts-1 and tts-1-hd. Both use the same engine and pricing. You can fetch the full list via GET /v1/models. The choice does not affect cost, only the specific audio generation parameters.

How do I set the language?

Pass the language parameter with an ISO code. If omitted, the system guesses from the script, defaulting to English for Latin text. Explicitly setting it ensures correct pronunciation for non-English Latin-script texts like French or German.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key. Before the first top-up, it is 10 per minute. Requests are processed sequentially, so excess requests may wait in a queue. Failed requests remain free, but successful ones count toward the limit.

Is there a character limit per request?

Yes, each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer texts, split them into parts under this limit and join the resulting audio files manually.

How do I handle long texts?

Split your text into chunks of 4096 characters or fewer. Send each chunk as a separate request. Then, join the returned audio files together. This ensures all text is processed within the single-request character limit.

What audio formats are supported?

Supported formats are mp3, wav, opus, flac, and pcm. Set the response_format field in your JSON body to your preferred type. The API returns the audio file directly in the response body.

Does the API return streaming data?

No. The API does not support streaming, WebSocket connections, or real-time partial audio. It returns the audio file upon successful synthesis. Requests are processed sequentially, so latency depends on queue position.

How do I rotate my API key?

Issue a new key from your account dashboard. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime for your applications.

What are the response headers?

The documentation does not specify custom response headers beyond standard HTTP status codes. The response body contains the audio file or error details. Use standard HTTP status codes to determine success or failure.

Can I use multiple keys?

Each account holds one active key at a time. You can issue a new key, which invalidates the previous one instantly. You cannot use multiple keys simultaneously with a single account; you must rotate them.

How do I check available voices?

Send a GET request to GET /v1/voices. This endpoint returns details on all 8 voice presets, supported languages, and formats. You can also view them on your dashboard after signing in.

First request

curl

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

Authentication

Sound wave illustration for: Authentication

Secure your API calls with a Bearer token. Include your key in the Authorization header for every request to ensure valid access to the text-to-speech engine.

Each account maintains one active key. If you generate a new key, the previous one becomes invalid immediately, ensuring tight control over access points.

Bearer Token Header

Bearer Token Header

Pass your API key as a Bearer token in the Authorization header. This standard method works seamlessly with official OpenAI SDKs by adjusting the base URL.

Example: Authorization: Bearer tts-...

One Active Key Per Account

One Active Key Per Account

Your account is tied to a single active API key. This simplifies security monitoring and billing attribution, as all usage traces back to one identifier.

You can view your current key and balance directly on the /get-api-key/ dashboard.

Key Rotation

You can issue a new key at any time via your dashboard. The old key stops working instantly, allowing you to rotate credentials without downtime if needed.

This is useful if you suspect a key has been exposed or want to reset access for a specific team member.

Endpoint Overview

Sound wave illustration for: Endpoint Overview

Our API follows a familiar structure, making integration straightforward for mobile teams already using standard HTTP clients or the OpenAI SDK. You interact with three core endpoints to generate audio, discover available voices, and check model details.

POST /v1/audio/speech

This is your primary endpoint. Send a JSON body with your text, selected voice, and preferred format to receive an audio file directly in the response. The request shape matches the OpenAI speech endpoint, so you can simply update your base URL to https://api.playmk777.com/v1.

  • Accepts text up to 4096 characters
  • Returns audio in the specified format

GET /v1/voices

Use this endpoint to retrieve the list of eight available voice presets and their supported languages. It also returns the current pricing and supported audio formats, helping you decide which voice fits your app’s tone before you start generating.

GET /v1/models

Retrieve the available model identifiers, currently 'tts-1' and 'tts-1-hd'. Both models use the same engine and price point, allowing you to switch between them without changing your billing expectations.

Request Parameters

Sound wave illustration for: Request Parameters

Configure your API requests by selecting the synthesis model, defining the input text, and choosing a voice preset. These three parameters determine how the text is converted into audio and directly impact the output quality and processing behavior.

Model Selection

Specify the model as either "tts-1" or "tts-1-hd". Both use the same underlying engine and incur identical pricing, so choose based on your preference for audio fidelity without worrying about cost differences.

Input Text Limit

The input field accepts up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4,096 characters, generate each separately, and join the resulting audio files.

Voice Selection

Choose one of eight voice presets from the voice field. Female voices include aria, nova, luna, and sage. Male voices include felix, milo, atlas, and orion. Each voice offers a distinct tone suitable for different mobile app contexts.

Voices are licensed from LibriTTS-R and LibriVox public-domain readings. Every generated audio file contains an inaudible watermark indicating it is synthetic speech.

  • aria: warm, clear narrator
  • nova: bright, upbeat
  • luna: soft, storytelling
  • sage: calm, instructional
  • felix: energetic, promo
  • milo: friendly, conversational

Response Formats

Sound wave illustration for: Response Formats

The API returns raw binary audio data in the response_format you specify, with the correct Content-Type header so your mobile app can play or save the file directly.

MP3 Format

Use mp3 for broad compatibility. It offers a balance between file size and quality for mobile playback, keeping bandwidth costs low while ensuring playback across all devices.

WAV Format

Choose wav for uncompressed, high-fidelity audio. This format is ideal for local storage or processing pipelines where minimal decoding overhead is required, though files will be significantly larger than MP3.

OPUS, FLAC, PCM

OPUS provides excellent compression. FLAC offers lossless quality without the size of WAV. PCM returns raw linear audio samples, useful for direct DSP processing. Select the format that fits your app’s audio engine.

Speed Control

Sound wave illustration for: Speed Control

Adjusting the speed parameter lets you tailor audio pacing for different mobile use cases, from quick notifications to immersive storytelling. The API accepts a float value between 0.25 and 4.0, giving you granular control over how fast the synthetic voice speaks. This flexibility ensures your app’s audio matches the intended user experience without requiring post-processing.

Speed Range 0.25–4.0

You can specify any speed value within the 0.25–4.0 range. Lower values slow down the narration, which is useful for complex instructions or language learning. Higher values accelerate the speech, ideal for brief updates or keeping users engaged in fast-paced environments.

Default Speed

If you omit the speed parameter, the API uses a default pace that balances clarity and natural rhythm. This default is suitable for general-purpose applications, such as reading articles or providing standard app feedback.

Impact on Generation Time

Changing the speed does not significantly alter the time required for the API to process your request. Generation speed remains roughly real-time, processing about 25 characters per second regardless of the chosen pace. Under load, requests may queue, but the speed setting itself does not add latency.

Speed Control

Language Handling

Sound wave illustration for: Language Handling

Language handling ensures your synthesized audio matches the intended audience. You can explicitly set the language using an ISO code or rely on automatic detection based on the input text script.

ISO Language Code

Pass the language parameter with a supported ISO code (e.g., es, fr, de) to force specific output. This guarantees consistency regardless of the input text's script.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish. Any voice can speak any of these languages.

Automatic Detection

If language is omitted, the API guesses the language from the input text. This works well for standard inputs but may misidentify mixed-script text.

Latin Script Default

Latin-script text defaults to English if no language is specified. For non-English Latin text (e.g., German or Spanish), always set the language parameter to avoid English pronunciation.

Rate Limits

Sound wave illustration for: Rate Limits

Understanding rate limits ensures your mobile app generates audio smoothly without unexpected interruptions. Our API balances performance with fair usage, allowing product teams to scale their TTS features predictably. Knowing how requests are queued helps you manage user expectations during high traffic.

Rate limits apply per API key, so each account has its own quota. This structure is simple to implement and works well with standard HTTP clients or the OpenAI SDK.

60 Requests Per Minute

Once your account is active, you can make up to 60 requests per minute. This limit applies to all requests sent with your API key, regardless of the voice or format used.

This steady throughput is sufficient for many mobile apps, allowing you to generate dozens of short phrases or a few longer narrations every minute.

10 Requests Before Top-Up

New accounts start with a lower limit of 10 requests per minute. This applies until you add your first top-up of at least $5 via USDT (TRC-20).

Once your balance is updated, your rate limit increases to the standard 60 requests per minute, allowing your app to scale immediately.

Queue Behavior

Requests are processed sequentially. If you exceed the limit, new requests may wait in a queue rather than failing immediately. This ensures requests are processed, though it may increase latency.

For time-sensitive user interactions, consider implementing a retry mechanism with exponential backoff to handle temporary delays gracefully without frustrating your users.

Error Handling

Sound wave illustration for: Error Handling

Handling errors correctly ensures your mobile app remains responsive during synthesis failures or network hiccups. Since requests are processed sequentially, understanding failure states helps you manage user expectations without unnecessary retries.

Common Error Codes

The API returns standard HTTP status codes. A 400 Bad Request indicates invalid JSON or missing fields. A 401 Unauthorized means your Bearer token is missing or invalid. Check your key format carefully.

Input Validation

If your input text exceeds 4096 characters or contains unsupported encoding, the request fails immediately. The response body includes a specific error message detailing the validation rule that was broken. Ensure your client truncates or splits text before sending.

Rate Limit Errors

You receive a 429 Too Many Requests error if you exceed 60 requests per minute. New accounts start with a limit of 10 requests per minute until the first top-up. Respect the Retry-After header to avoid queueing delays.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. There is no complex streaming protocol required; the audio is returned as a complete file.

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

More on this site