API Documentation for YouTube Voiceover Automation

By AudioScribe editorial team · Updated 2026-11-18

This documentation explains how to integrate the AudioScribe text-to-speech API into your YouTube content workflow. You will learn to convert scripts into high-quality voiceovers programmatically, automating narration for videos, shorts, and tutorials without hiring voice actors or mastering complex editing tools. The guide covers authentication, endpoints, and parameters specific to our API.

Designed for no-code creators, this page provides concrete examples using cURL and the OpenAI SDK. We detail how to manage API keys, handle rate limits, and select voices or formats. Whether you are building a simple script or a complex automation pipeline, these instructions help you generate audio files efficiently and integrate them directly into your production process.

API Documentation for YouTube Voiceover Automation

Frequently asked questions

How do I get my API key?

Sign up on the /get-api-key/ page using Google or email. Your unique API key appears immediately on the dashboard alongside your balance and usage stats. You can issue a new key at any time, which instantly invalidates the previous one.

Can I use the OpenAI Python SDK?

Yes. The API uses the same request shape as OpenAI’s speech endpoint. Simply change the base_url to https://api.je1688.com/v1 and use your AudioScribe key. The official OpenAI SDKs work directly without modification.

What is the base URL for the API?

The API base URL is https://api.je1688.com/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 your Bearer token.

How do I handle rate limit errors?

You are limited to 60 requests per minute per key (10 before the first top-up). Requests are processed sequentially, so under load, you may wait in a queue. Implement retry logic with exponential backoff to handle 429 errors gracefully.

Can I send text longer than 4096 characters?

Yes, but you must split the text into parts of up to 4096 characters. Generate audio for each part separately, then join the resulting audio files. This ensures each request stays within the character limit.

Does the API support SSML?

No, the API does not support SSML. You cannot use SSML tags for pronunciation or prosody control. For precise timing, generate separate audio segments and join them programmatically in your workflow.

How do I specify a language?

Pass the language field with an ISO code in the JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting it ensures accuracy for non-English content.

What happens if the API returns an error?

If synthesis fails, the charge is returned in full. Failed requests are free. You can retry the request after fixing any issues with the input text, voice, or model parameters without losing your credit.

Can I use the same key for multiple projects?

Yes, one active key per account works across multiple projects. You can issue a new key at any time, which instantly stops the old one. This allows you to rotate keys for security or project separation.

Is the API JSON-based?

Yes, the API accepts JSON bodies for requests. Send your text, voice, and model parameters in JSON format to the /v1/audio/speech endpoint. The response contains the audio file, typically in formats like mp3, wav, or opus.

Do I need to install extra libraries?

No, you do not need extra libraries. You can use plain HTTP requests or the official OpenAI SDKs. Just configure the base URL and authorization header. No proprietary SDK or specific Python packages are required.

How do I test the API without spending credits?

Sign up with Google to receive a $0.50 free trial credit, valid for 7 days. This covers about 50,000 characters. Accounts created with email and password start without this trial credit.

Can I download the audio file directly?

Yes, the API returns the audio file directly in the response. You can save it to your local storage. Supported formats include mp3, wav, opus, flac, and pcm.

What is the default voice if none is specified?

The API requires a voice parameter; there is no implicit default. You must specify one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Check the /v1/voices endpoint for the full list.

First request

curl

curl https://api.je1688.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.je1688.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.je1688.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 access by generating a unique key on the /get-api-key/ page. You can sign up using Google or an email password. The dashboard displays your active key, current balance, and usage statistics immediately after creation.

Generate Your API Key

Generate Your API Key

Navigate to the dashboard to create your first key. One active key is issued per account. If you need a fresh credential, you can generate a new one at any time, which instantly invalidates the previous key.

Bearer Token Usage

Bearer Token Usage

Include your key in the HTTP header as Authorization: Bearer tts-.... This token authenticates all requests to the API endpoint. Keep it secure and do not expose it in public client-side code.

Key Rotation Policy

Rotate keys freely via the dashboard. When a new key is issued, the old one stops working immediately. This ensures you can revoke access instantly if needed without waiting for expiration.

Endpoints

Sound wave illustration for: Endpoints

The AudioScribe API exposes three core endpoints to manage voice generation, discovery, and model details. These endpoints follow standard REST conventions, ensuring seamless integration into your existing YouTube automation pipelines without requiring proprietary libraries.

POST /v1/audio/speech

This is your primary endpoint for generating audio. Send a JSON body containing the text, voice selection, and format preferences to receive an audio file. The endpoint supports texts up to 4096 characters per request, making it ideal for short video segments or individual scenes.

GET /v1/voices

Retrieve the full list of available voice presets, their associated languages, and supported audio formats. This endpoint helps you dynamically select a voice for your content style, such as using 'aria' for warm narration or 'atlas' for news-style updates.

GET /v1/models

View the available TTS models, including 'tts-1' and 'tts-1-hd'. Both models use the same engine and pricing, allowing you to switch between standard and high-definition quality based on your production needs without changing your integration logic.

Request Parameters

Sound wave illustration for: Request Parameters

Configure your synthesis requests with precise control over audio quality, voice character, and playback speed. These parameters determine how your text transforms into the final audio file delivered by the API.

Model Selection

Choose between "tts-1" for standard efficiency or "tts-1-hd" for higher fidelity. Both models use the same underlying engine and pricing, so select based on whether you prioritize processing speed or audio clarity for your YouTube narration.

  • tts-1: Standard quality
  • tts-1-hd: Higher fidelity
  • Same price: $0.01 per 1,000 characters

Voice Presets

Select from eight distinct voice presets tailored for different content styles. Female voices like Aria offer a warm, clear narration style, while Male voices like Atlas provide a neutral, news-like tone. You can also use Luna for soft storytelling or Felix for energetic promos, as well as Sage, Milo, Atlas, and Orion.

  • Aria: Warm, clear narrator
  • Felix: Energetic, promo style
  • Atlas: Neutral, news tone
  • Luna: Soft, storytelling vibe

Speed and Format

Adjust the playback speed between 0.25 and 4.0 to match your video pacing. Choose your output format from mp3, wav, opus, flac, or pcm. MP3 is ideal for web playback, while WAV offers lossless quality for further editing in your video software.

  • Speed: 0.25 to 4.0
  • Formats: mp3, wav, opus, flac, pcm
  • Language: Optional ISO code for accurate synthesis

cURL Example

Sound wave illustration for: cURL Example

This section demonstrates how to generate audio using standard command-line tools, ideal for quick testing or simple automation scripts. You can use cURL to send text directly to the API and save the resulting audio file locally.

The example below uses the tts-1 model with the nova voice to create a bright, upbeat narration.

Basic Request Structure

To start, issue a POST request to the speech endpoint. Replace YOUR_API_KEY with your actual key from the dashboard.

The command sends a JSON payload containing the text, model, voice, and output format.

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

Headers and Body

Ensure the Authorization header includes the Bearer prefix followed by your key. The body must contain model, input, voice, and response_format. The input field supports up to 4096 characters.

You can optionally set a speed parameter between 0.25 and 4.0 to adjust playback rate without affecting voice quality.

Response Handling

On success, the API returns the audio file directly in the response body with a content-type matching your requested format. Save this output to a file using shell redirection.

If the request fails, check the HTTP status code and error message in the response JSON for details on invalid parameters or authentication issues.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

To integrate AudioScribe with existing OpenAI SDKs, update the base_url to point to our API endpoint. This allows you to use familiar client libraries while routing requests through our text-to-speech infrastructure.

Base URL Configuration

Set the OpenAI client's base_url to https://api.je1688.com/v1. This directs all standard speech requests to our endpoint while maintaining compatibility with the official SDK structure.

Client Initialization

Initialize the client using your API key obtained from the dashboard. The same key format (tts-...) works with OpenAI’s Python or JavaScript libraries, requiring only the URL adjustment.

  • Use the key from your /get-api-key/ dashboard.

Code Snippets

Pass your script text to the speech endpoint. The SDK handles JSON serialization, returning audio files in your chosen format (mp3, wav, opus, flac, or pcm).

Example: `client.audio.speech.create(model="tts-1", voice="nova", input="Hello world", response_format="mp3")`.

OpenAI SDK Integration

Error Handling

Sound wave illustration for: Error Handling

Synthesis failures are free. If the API returns an error, you receive a full refund for that request, so you can retry without losing credit.

Always check the status code. A 2xx response means the audio file is ready in the response body. Anything else indicates a problem that needs attention.

Common Error Codes

Use standard HTTP codes to diagnose issues. A 400 error usually means your input text exceeds the 4096 character limit, contains invalid JSON, or has invalid parameters. A 401 error indicates an invalid or expired API key. Check your dashboard to ensure the key is active.

A 500 error indicates a server-side issue. Requests are processed sequentially, so under load a request may wait in a queue. If you see this, wait a moment and retry.

  • 400: Bad Request (invalid text or format)
  • 401: Unauthorized (invalid API key)
  • 500: Internal Server Error (temporary issue)

Retry Logic

Implement exponential backoff for transient errors. Start with a 1-second delay, then double it for each retry attempt. This prevents overwhelming the server during high demand.

Only retry on 5xx errors or 429 (Rate Limit). Do not retry on 400 errors, as they will fail repeatedly with the same input. Always verify your text length before retrying.

  • Wait 1 second, then 2, 4, 8 seconds, etc.
  • Max retries: 3 attempts
  • Retry only on 5xx or 429 errors

Rate Limit Errors

You have a limit of 60 requests per minute per key. If you exceed this, you will receive a 429 Too Many Requests error. Your new key starts with a 10 requests per minute limit.

After topping up, the limit increases to 60 requests per minute. Monitor your usage dashboard to stay within limits. If you hit the limit, wait until the window resets or top up your balance.

  • 60 requests per minute (standard)
  • 10 requests per minute (new accounts)
  • Reset every 60 seconds

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits protect the service during peak usage. The standard limit is 60 requests per minute per API key, allowing steady automation for most YouTube workflows. Requests are processed sequentially, so longer texts may queue slightly during high load.

60 Requests Per Minute

Each API key supports up to 60 requests per minute. This limit applies to all requests, including those for short phrases or long texts split into multiple parts. Plan your batch sizes accordingly to avoid temporary throttling.

Initial Limit for New Accounts

New accounts start with a lower limit of 10 requests per minute. This helps stabilize the system while your account is new. You can generate a new key anytime, but the limit is based on the account's top-up status, not the key itself.

Limit Increase After Top-Up

After your first top-up of $5 or more via USDT (TRC-20), your limit increases to the standard 60 requests per minute. The change is automatic and takes effect within minutes of the transfer confirmation.

Audio Formats

Sound wave illustration for: Audio Formats

AudioScribe supports multiple output formats to suit different stages of your YouTube production pipeline. You can choose between MP3, WAV, Opus, FLAC, or PCM depending on your specific needs for compatibility, quality, or editing flexibility.

MP3 Compatibility

MP3 is the standard choice for most YouTube uploads. It offers a good balance between file size and audio quality, ensuring your voiceovers play smoothly across all devices and browsers without consuming excessive bandwidth.

  • Supported by all major video platforms
  • Small file size for faster uploads

WAV for Editing

Use WAV when you need uncompressed, high-quality audio for post-production. This format preserves the full fidelity of the synthesis, making it ideal for precise editing, mixing, or adding sound effects in your video editing software.

  • Uncompressed audio quality
  • Ideal for professional editing workflows

Opus for Streaming

Opus provides efficient compression with high quality, suitable for modern streaming applications. While not directly uploadable to YouTube, it is excellent for internal prototypes or integrating the audio into web-based players that support the format.

  • High compression efficiency
  • Low latency for web integration

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Viewers expect factual delivery without emotional bias, making voice selection critical for trust.

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. MDN: Web Speech API
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. W3C WAI: making audio and video accessible
  6. ISO 639 language codes
  7. OpenAI API reference: create speech
  8. Creative Commons Attribution 4.0
  9. Tether (USDT)
  10. FFmpeg documentation
  11. TRON developer hub: TRC-20
  12. Python documentation

More on this site