API Documentation for Cloud Text-to-Speech

By NarrateNow editorial team · Updated 2026-11-18

This guide shows you how to turn your blog posts, scripts, and notes into natural-sounding audio using the NarrateNow API. You will learn to send a simple POST request, receive an audio file, and integrate the service into your YouTube workflow. We cover authentication, parameters, and formats so you can generate royalty-free speech in 23 languages without recording equipment.

Designed for freelancers and content creators, this documentation explains every step from getting your API key to handling errors. You will see exactly how the 4096-character limit works, how to manage rate limits, and how to use the OpenAI SDK with our base URL. No complex setup, just clear examples for generating voiceovers.

API Documentation for Cloud Text-to-Speech

Frequently asked questions

How do I get my API key?

Sign up on the /get-api-key/ page using Google or email plus password. The dashboard displays your active API key, current balance, and usage statistics. You can issue a new key at any time, which immediately invalidates the previous one. Each account is tied to this specific site.

What is the base URL for the API?

The API base URL is https://api.heng9999th.com/v1. You send POST requests to https://api.heng9999th.com/v1/audio/speech. This endpoint accepts JSON bodies identical to the OpenAI speech endpoint format, ensuring compatibility with standard HTTP clients and SDKs that support custom base URLs.

Can I use the OpenAI Python SDK?

Yes, the official OpenAI SDKs work perfectly. You simply change the base_url to https://api.heng9999th.com/v1 and use your NarrateNow API key. This allows you to generate audio using familiar code structures without needing a custom library or wrapper specific to our platform.

What is the maximum text length?

Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. If your script exceeds this length, you should split it into smaller parts and join the resulting audio files after generation to ensure consistent quality and processing.

How do I set the language?

Include the optional 'language' field with an ISO code in your request. If omitted, the system guesses the language, defaulting to English for Latin script text. For non-English Latin text, explicitly setting the language ensures accurate pronunciation and avoids incorrect language detection errors.

What happens if I exceed the rate limit?

You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. Before your first top-up, the limit is 10 requests per minute. Failed requests do not consume your credit, so retrying after the limit resets is safe.

Is the API key secure?

Yes, authenticate requests using the 'Authorization: Bearer tts-...' header. Each account has one active key. You can issue a new key at any time, which instantly stops the old one from working. This ensures that if a key is compromised, you can immediately revoke access.

Can I generate multiple voices at once?

No, each request generates audio for a single voice. To create content with multiple voices, send separate requests for each voice preset. The system processes requests sequentially, so generating multiple voices will take time proportional to the total character count and current queue load.

What formats are supported?

You can choose between mp3, wav, opus, flac, or pcm formats. Select the desired format using the 'response_format' field in your JSON body. MP3 is recommended for general use, while WAV or FLAC offers higher quality for professional editing workflows requiring lossless audio.

How do I handle long texts?

Split your text into chunks of up to 4096 characters. Generate audio for each chunk individually using separate API calls. Then, join the resulting audio files using your preferred editor or script. This method ensures reliable processing and avoids hitting character limits during synthesis.

Are there any SDKs for mobile?

We do not offer a dedicated mobile SDK. You can use the standard OpenAI SDKs or plain HTTP requests on any platform. Since the API uses standard JSON over HTTPS, it works seamlessly on iOS, Android, and other mobile environments with basic networking capabilities.

Is there an SSML tag supported?

No, the API does not support SSML tags. You cannot use phoneme dictionaries or custom pronunciation lexicons either. The system uses simple text input with optional language codes.

How do I check my usage?

Visit the /get-api-key/ page on our site. The dashboard displays your current balance, trial status, characters remaining, and usage history. You can also see your active API key and a ready-to-use cURL example directly on this page for quick reference.

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

Both models use the same engine and price ($0.01 per 1,000 characters). The 'tts-1-hd' model offers slightly higher audio quality, while 'tts-1' is optimized for speed. Both support all eight voices and 23 languages, with identical character limits and rate limits per request.

First request

curl

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

Quickstart: Your First Request

Sound wave illustration for: Quickstart: Your First Request

Turn blog posts or scripts into natural-sounding audio with a single API call. This quick guide shows how to generate your first audio file in under a minute.

Get your API key

Get your API key

Sign up at /get-api-key/ using Google or email to generate your key. You’ll receive $0.50 in free trial credit, valid for 7 days, covering about 50,000 characters.

Send a POST request

Send a POST request

Send your text to the speech endpoint using a standard HTTP POST request. Include your Bearer token in the header and specify the voice and language.

  • Endpoint: POST https://api.heng9999th.com/v1/audio/speech
  • Header: Authorization: Bearer tts-...
  • Body: JSON with model, input, voice, and response_format

Receive your audio file

Receive the audio file directly in the response. For longer texts, split the input into chunks of 4096 characters and join the resulting audio files.

Authentication and Keys

Sound wave illustration for: Authentication and Keys

Secure your audio generation with a single Bearer token. Pass your API key in the Authorization header of every request to authenticate your account and track usage against your balance.

Bearer token in header

Include your key as Authorization: Bearer tts-... in every HTTP request. This simple header ensures only your account can generate audio and deducts credits from your specific balance.

One active key per account

Each account maintains exactly one active API key at any time.

Revoke old keys instantly

Issue a new key at any time via your dashboard. The previous key stops working immediately, ensuring no unauthorized usage continues if your credentials are exposed or shared.

  • Generate a new key instantly
  • Old key becomes invalid immediately
  • No waiting period for security

Request Parameters

Sound wave illustration for: Request Parameters

Send a JSON payload to the speech endpoint. You must include the model, input, voice, and response_format fields. The input field accepts plain text up to 4096 characters; spaces and punctuation count toward this limit.

Model selection (tts-1, tts-1-hd)

Choose between tts-1 and tts-1-hd. Both models use the same underlying engine and have identical pricing, so pick based on your preference for audio quality versus generation speed.

Input text limit (4096 chars)

Each request supports a maximum of 4096 characters of input text. If your script or blog post exceeds this length, split the text into smaller chunks and join the resulting audio files on your end.

Voice and language settings

Select one of the eight preset voices, such as nova for upbeat content or atlas for neutral narration. You can optionally specify a language ISO code (e.g., en, de, ja). Without it, the system guesses the language, defaulting to English for Latin script.

  • 8 preset voices available
  • 23 supported languages
  • Optional language code parameter

Supported Response Formats

Sound wave illustration for: Supported Response Formats

Choose the audio format that best fits your workflow. MP3 is the standard choice for web delivery and YouTube videos, offering a good balance of file size and compatibility. WAV provides uncompressed audio for projects requiring maximum fidelity, while FLAC and Opus offer lossless compression for efficient storage without quality loss.

MP3 for web and YouTube

Use MP3 for most use cases. It is widely supported by video editors and social media platforms, making it ideal for YouTube creators who need royalty-free speech that integrates seamlessly into their content.

WAV for uncompressed audio

Select WAV when you need uncompressed audio. This format is best for professional editing workflows where you want to preserve the exact audio data without any compression artifacts.

FLAC and Opus options

Use FLAC for lossless compression. It provides smaller files than WAV while maintaining full quality. Opus is another efficient option for streaming or storage-constrained environments.

Rate Limits and Queues

Sound wave illustration for: Rate Limits and Queues

Our API handles requests at a steady pace. You can send up to 60 requests per minute once your account is fully funded. This limit ensures consistent audio generation without overwhelming the service.

60 requests per minute

Standard accounts can process 60 requests per minute. This allows you to generate multiple voiceovers quickly for your YouTube videos or freelance projects.

10 requests before top-up

New accounts start with a lower limit of 10 requests per minute. This applies until you make your first top-up. Once funded, your limit increases to the full 60 requests per minute.

Queue behavior under load

Requests are processed sequentially. If the system is busy, your request may wait in a queue. Longer texts take more time to generate, so plan your workflow accordingly. Short phrases still take a few seconds.

  • Requests are processed one after another
  • Queue waits may occur during high load
  • No parallel processing for a single key
Rate Limits and Queues

Error Handling and Codes

Sound wave illustration for: Error Handling and Codes

When your request fails, the API returns a JSON error object with a code and message. This helps you quickly identify if the issue is authentication, limits, or input size. Always check the HTTP status code alongside the response body to determine the next step in your workflow.

Invalid keys can be regenerated, rate limits reset after a minute, and text can be split to fit character constraints. Keeping your error handling robust ensures your YouTube audio generation pipeline stays reliable even during peak usage hours.

Invalid API key errors

If you send a request with an expired or incorrect key, the API returns a 401 Unauthorized error. This happens if the key was revoked after issuing a new one, or if the header format is incorrect.

Check that your Authorization header includes the correct Bearer token. You can regenerate your key instantly from your dashboard to resolve this issue.

  • 401 Unauthorized: Check your Bearer token in the Authorization header.
  • 403 Forbidden: The key may have been revoked.

Rate limit exceeded

You are limited to 60 requests per minute with a valid key, or 10 requests per minute before your first top-up. If you exceed this, the API returns a 429 Too Many Requests error.

Implement exponential backoff in your code to retry after the rate limit window resets. This prevents overwhelming the queue during high-volume YouTube content creation bursts.

  • 429 Too Many Requests: Wait before retrying.

Text too long errors

Each request accepts a maximum of 4096 characters for the input text. If your script exceeds this limit, the API returns a 400 Bad Request error.

Split your text into chunks of 4096 characters or less. Generate audio for each chunk and join the resulting audio files to create a complete voiceover for your video.

  • 400 Bad Request: Input text exceeds 4096 characters.
  • Split your text into smaller segments before sending the POST request.

Using the OpenAI SDK

Sound wave illustration for: Using the OpenAI SDK

Leverage your existing familiarity with OpenAI’s ecosystem by simply redirecting the SDK’s base URL. Instead of the default OpenAI endpoint, configure the client to point to https://api.heng9999th.com/v1. This single change allows you to use the official OpenAI Python or Node.js SDKs without rewriting your entire integration logic.

Change base_url to our API

Update your client configuration to use our API base URL. This ensures all subsequent requests are routed correctly to our infrastructure while maintaining the standard SDK behavior you expect.

  • Base URL: https://api.heng9999th.com/v1
  • Works with official OpenAI SDKs
  • No code changes needed for request bodies

Use official SDKs

You can use the official OpenAI SDKs for Python or Node.js. Since our API endpoint mirrors the OpenAI speech endpoint structure, the same libraries handle authentication, retries, and response parsing seamlessly.

Compatible request shape

Our API accepts the exact same JSON body structure as the OpenAI /v1/audio/speech endpoint. Pass your model, input text, voice, and response_format exactly as you would for OpenAI. The only difference is the base_url configuration.

Voice and Model Details

Sound wave illustration for: Voice and Model Details

NarrateNow offers eight distinct voice presets, ranging from the warm, clear narration of Aria to the deep, documentary-style tone of Orion. You can also choose between the standard tts-1 and high-definition tts-1-hd models, which use the same engine and pricing.

Support spans 23 languages, including English, Spanish, and Japanese. Any voice can speak any supported language; if the language parameter is omitted, the system guesses from the script, defaulting to English for Latin text.

8 preset voices available

Choose from female voices like Luna for soft storytelling or Nova for upbeat content, and male options like Felix for energetic promos or Milo for friendly conversation. Neutral and instructional tones are available via Atlas and Sage.

Each generated file includes an inaudible watermark marking it as synthetic speech. All voices are derived from licensed recordings.

  • Aria: Warm, clear narrator
  • Luna: Soft, storytelling
  • Felix: Energetic, promo
  • Atlas: Neutral, news
  • Nova: Bright, upbeat
  • Sage: Calm, instructional

23 supported languages

The API supports Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

For non-English Latin-script text, explicitly set the language parameter to ensure accurate pronunciation, as the system defaults to English for Latin scripts.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Real-time speed estimation

Generation speed is roughly real-time on long texts, averaging about 25 characters of text per second of audio generated. Short phrases may take a few seconds to process.

Requests are processed sequentially, so under heavy load, your request may wait in a queue before synthesis begins.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence.

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

More on this site