API Documentation for Voiceover Generation

By ShortForm AI editorial team · Updated 2026-11-18

This guide provides the essential endpoints and parameters for generating voiceovers programmatically. It is designed for developers building automation pipelines for TikTok, Reels, and Shorts who need reliable, synthetic audio without manual recording. You will find concrete cURL examples, SDK integration steps, and precise specifications for models, voices, and response formats.

The documentation covers authentication, rate limits, and error handling to help you integrate the API smoothly. It assumes you are comfortable with HTTP requests and JSON. All examples use the standard OpenAI-compatible format, allowing you to swap the base URL and start generating audio immediately with minimal code changes.

API Documentation for Voiceover Generation

Frequently asked questions

How do I get an API key?

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

What is the base_url for the OpenAI SDK?

Change the base_url to https://api.play78j.com/v1. The request shape matches the OpenAI speech endpoint, so official OpenAI SDKs work directly. Use the tts-1 or tts-1-hd model with your site-specific key for authentication.

Can I use the Python SDK?

Yes, the official OpenAI Python SDK works by updating the base_url to https://api.play78j.com/v1. We do not provide a custom SDK, so you must use the standard OpenAI client library with the adjusted endpoint configuration.

What happens if I exceed the rate limit?

The limit is 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load a request may wait in a queue.

How do I change the voice speed?

Include the speed field in your JSON body with a value between 0.25 and 4.0. The default speed is 1.0. Adjust this parameter to make the voice faster or slower.

Is the API compatible with ElevenLabs SDK?

No. The API is compatible with the OpenAI SDK because it uses the same request shape.

What is the maximum text length?

Each request supports up to 4096 characters. For longer texts, split the input into chunks of 4096 characters, generate audio for each, and join the resulting files. Spaces and punctuation count toward this character limit.

How do I specify the language?

Include the optional language field with an ISO code in your request. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly set it for non-English Latin-script text.

Do I need to handle audio file decoding?

No. The API returns the audio file directly in the response body. You can save the response content as an MP3, WAV, OPUS, FLAC, or PCM file depending on your chosen response_format parameter.

Can I send multiple texts in one request?

No. Each POST request handles a single text input up to 4096 characters. To generate multiple segments, you must send separate requests for each text chunk and then concatenate the resulting audio files.

What is the difference between tts-1 and tts-1-hd?

Both models use the same engine and price. The difference is the model identifier string in your request. Both models use the same engine and price ($10 per 1 million characters).

How do I authenticate my requests?

Include the header Authorization: Bearer tts-... with your unique API key. Generate this key on the /get-api-key/ page. Ensure the key is valid and active, as issuing a new one immediately invalidates the previous one.

Is there a WebSocket endpoint?

No. The API is a standard REST endpoint using POST for speech generation. There is no WebSocket support for real-time streaming or partial audio delivery. You must wait for the full audio file response.

Do I need an IP whitelist?

No. Authentication is handled via the Bearer token in the Authorization header. There is no IP whitelist feature, so you can make requests from any IP address as long as you provide a valid API key.

First request

curl

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

Access the API using a Bearer token sent in the Authorization header. You obtain your key by signing in via Google or email on the /get-api-key/ page. Each account holds one active key, which is displayed alongside your current balance and usage statistics.

Get your API key

Get your API key

Sign up on the /get-api-key/ page using Google or an email/password combination. Google sign-ups receive a $0.50 free trial credit valid for 7 days. Email-based accounts start with zero credit.

  • Google sign-in includes $0.50 trial credit
  • Email sign-in requires immediate top-up
  • One key per account shown on dashboard

Bearer token format

Bearer token format

Include your key in the request header as Authorization: Bearer tts-.... The key format is standard, ensuring compatibility with the OpenAI SDKs by simply changing the base_url to https://api.play78j.com/v1.

Regenerate keys

Issue a new key at any time via your dashboard. The old key stops working immediately upon generation of the new one, ensuring secure access for your automated voiceover pipelines.

Quickstart with cURL

Sound wave illustration for: Quickstart with cURL

Generate voiceovers for TikTok and Shorts by sending a POST request to the API. The endpoint accepts JSON bodies with your text and preferred voice settings, returning an audio file directly in the response.

Use the following cURL command as a template. Replace YOUR_API_KEY with your secret token and update the input text to match your script. This method works for any supported language and voice preset.

Basic request example

Here is a minimal request to generate speech using the default model and voice.

  • curl -X POST https://api.play78j.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova"}'

Required fields

Every request must include the model and input fields.

  • model: "tts-1" or "tts-1-hd"
  • input: text string (max 4096 chars)
  • voice: one of the 8 presets
  • Authorization: Bearer <key>

Response format

The API returns the audio file directly in the response body. The format matches your response_format parameter, defaulting to MP3. You can pipe this directly into your video editing pipeline.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integration logic with minimal changes. By simply adjusting the base URL, you can leverage the official OpenAI SDKs for Python, Node.js, and other languages without writing custom HTTP clients.

Set base_url

Point your SDK client to our API base URL: https://api.play78j.com/v1. This ensures all requests, including those from the official OpenAI SDK, route correctly to our infrastructure.

Use official SDKs

You can use the standard OpenAI SDKs. No custom client library is required. This works because our request and response shapes match the OpenAI speech endpoint specification exactly.

Code example

Initialize the client with your API key and the custom base URL. Then call the audio.speech.create() method with your text, voice, and model parameters.

  • Replace OPENAI_API_KEY with your tts-... key
  • Set base_url to https://api.play78j.com/v1
  • Use model: 'tts-1' or tts-1-hd
  • Specify voice from the 8 available presets

Request Parameters

Sound wave illustration for: Request Parameters

Configure synthesis parameters via the JSON request body. Select the model engine, voice preset, and optional speed or language constraints to define the output audio characteristics.

Model selection

Choose between "tts-1" or "tts-1-hd". Both use the same engine and pricing tier, so select based on your preference without affecting cost or performance.

Voice presets

Select one of eight licensed presets. Female voices include aria, nova, luna, and sage. Male voices include felix, milo, atlas, and orion. Each voice supports all 23 languages.

  • 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 and language

Adjust speed between 0.25 and 4.0. The optional language field accepts an ISO code; if omitted, the system guesses from the script, defaulting to English for Latin text.

Response Formats

Sound wave illustration for: Response Formats

Choose your output format via the response_format parameter. MP3 is the default and most efficient for web delivery, offering small file sizes that load quickly in TikTok and Reels editors. WAV provides uncompressed, high-quality audio ideal for final editing in professional suites.

OPUS and FLAC serve specific needs: OPUS offers efficient compression for mobile apps, while FLAC provides lossless quality for archival purposes. All formats are generated as single audio files per request, ready for immediate download or piping into your video pipeline.

MP3 output

Use mp3 for standard web playback. It balances quality and file size, making it the default choice for most short-form video workflows. The encoded audio is immediately playable in standard video editors.

  • Default format for most integrations
  • Small file size reduces upload times
  • Compatible with all major video platforms

WAV output

Select wav for uncompressed PCM audio. This format preserves full fidelity without lossy compression artifacts, preferred by editors who need clean audio stems for post-production mixing or noise reduction.

  • Uncompressed, lossless quality
  • Ideal for professional editing workflows
  • Larger file size than MP3

OPUS and FLAC

OPUS provides efficient compression suitable for mobile apps or low-bandwidth streaming. FLAC offers lossless compression, retaining all audio data while reducing file size compared to WAV. Choose FLAC when you need perfect quality but want to save storage space.

  • OPUS: Efficient compression for mobile
  • FLAC: Lossless compression for archival
  • Both support high-quality audio retention
Response Formats

Rate Limits

Sound wave illustration for: Rate Limits

Your API key allows 60 requests per minute. This limit applies to the key, not the account. You can monitor usage in the dashboard. If you exceed the limit, requests will fail until the window resets.

Before your first top-up, you are limited to 10 requests per minute. This ensures stable performance for new accounts. After topping up, the full 60 requests per minute limit becomes available immediately.

60 requests per minute

Each API key supports up to 60 requests per minute. This rate applies uniformly across all endpoints. You can check your current usage and limits in the dashboard.

  • Limit is per key, not per account
  • Applies to all request types
  • Check usage in the dashboard

10 requests before top-up

New accounts start with a limit of 10 requests per minute. This applies until you add funds via USDT (TRC-20). Once topped up, the limit increases to 60 requests per minute (10 per minute before the first top-up).

  • Starts at 10 req/min
  • Increases to 60 req/min after top-up
  • No minimum spend required

Queue behavior

Requests are processed sequentially. Under load, a request may wait in a queue before being processed. Typical speed is roughly real time for long texts. Short phrases take a few seconds to generate.

  • Processed sequentially
  • May wait in queue under load
  • Real-time speed for long texts

Error Handling

Sound wave illustration for: Error Handling

API errors are standard HTTP status codes. We return clear messages for invalid requests, ensuring you can debug quickly without guessing.

Common error codes

Use 400 for bad requests, 401 for authentication issues, and 429 for rate limits. Check the response body for specific details.

Retry logic

Implement exponential backoff for 429 errors. Requests are processed sequentially, so brief delays help avoid queue congestion during peak loads.

  • Start with a 1-second delay.
  • Increase delay exponentially for subsequent failures.
  • Stop after 3-4 attempts to avoid timeouts.

Failed request refund

If synthesis fails, the charge is returned in full. You are only billed for successful audio generations. This ensures you pay only for usable content.

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for generating and managing voiceovers. The core speech generation endpoint accepts text and configuration parameters to return audio files directly.

Metadata endpoints allow you to dynamically fetch available voices, supported formats, and pricing details, enabling programmatic configuration without hardcoding values.

POST /v1/audio/speech

Send a JSON body with model, input, voice, response_format, and optional speed or language. The endpoint returns the audio file directly in the response body. Text is limited to 4096 characters per request.

  • Endpoint: POST https://api.play78j.com/v1/audio/speech
  • Auth: Authorization: Bearer tts-...
  • Returns: Audio file in specified format

GET /v1/voices

Returns a list of all available voice presets, their associated languages, and supported output formats. Use this endpoint to populate UI dropdowns dynamically.

  • Endpoint: GET https://api.play78j.com/v1/voices
  • Returns: JSON array of voice objects
  • Includes: Voice ID, name, and supported languages

GET /v1/models

Returns the available TTS models (tts-1 and tts-1-hd) with their respective pricing and format support. Both models use the same underlying engine.

  • Endpoint: GET https://api.play78j.com/v1/models
  • Returns: JSON array of model objects
  • Includes: Model ID, name, and price per character

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Matching voice personas to your target demographic helps align audio tone with viewer expectations.

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. Node.js documentation
  4. IETF RFC 7845: Ogg Opus
  5. MDN: Web Speech API
  6. TRON developer hub: TRC-20
  7. OpenAI API reference: create speech
  8. W3C WAI: making audio and video accessible
  9. FFmpeg documentation
  10. openai-node on GitHub
  11. Creative Commons Attribution 4.0
  12. openai-python on GitHub

More on this site