Start with API Keys, Curl, and SDK Integration

By SuckBetth editorial team · Updated 2026-11-18

This guide walks indie developers through integrating the SuckBetth TTS API, from obtaining your first API key to generating audio with a simple curl command. You will learn how to configure the OpenAI SDK for our endpoints, manage request parameters like voice and speed, and handle responses in formats like MP3 or WAV.

Designed for product teams who value flexibility, this page covers authentication, rate limits, and error handling. We provide concrete code examples and explain how to rotate keys or debug requests, ensuring you can ship voice features quickly without managing complex infrastructure or waiting on support.

Start with API Keys, Curl, and SDK Integration

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.

Can I use the OpenAI Python SDK?

Yes. The request shape matches the OpenAI speech endpoint. Use the official OpenAI SDKs by changing the base_url to https://api.suckbetth.com/v1 and providing your site’s key. No custom SDK is required; standard HTTP requests work equally well.

What is the base URL for the API?

The API base URL is https://api.suckbetth.com/v1. Send POST requests to https://api.suckbetth.com/v1/audio/speech. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.

How do I set the voice parameter?

Set the voice parameter to one of the eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings. You can view the full list and details by calling the GET /v1/voices endpoint.

What is the character limit per request?

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

How do I handle rate limits?

The limit is 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so under load, a request may wait in a queue. Failed requests do not count toward limits.

What formats can I receive audio in?

You can receive audio in mp3, wav, opus, flac, or pcm formats. Specify your preferred format using the response_format parameter in your request body. The API returns the audio file directly in the response, not as a download link.

Does the API support speed control?

Yes, you can adjust the speech speed using the speed parameter. The valid range is 0.25 to 4.0. This allows you to make the speech slower or faster than the default rate without affecting the voice selection or language.

How do I rotate my API key?

You can issue a new API key at any time from your account dashboard. When a new key is generated, the old one stops working immediately. This ensures that only your current active key can be used for authentication.

What happens if the request fails?

If synthesis fails, the charge is returned in full. You are not billed for failed requests. This applies to any error that prevents the audio file from being generated successfully. You can retry the request with the same parameters.

Is the response format JSON or audio?

The response contains the audio file itself, not just JSON metadata. The request body is JSON, but the response is the actual audio data in the format you specified. You can save this directly to a file or play it.

Can I specify a language code?

Yes, you can provide an optional ISO language code. If omitted, the language is guessed from the script, defaulting to English for Latin text. For non-English Latin-script text, explicitly setting the language parameter ensures accurate synthesis.

How do I test the API before paying?

Sign in with Google to receive a free trial of $0.50 credit, valid for 7 days. This covers about 50,000 characters. Accounts created with email and password start without trial credit. Failed requests are free regardless of account type.

Where can I find the list of voices?

Call the GET /v1/voices endpoint to retrieve the list of available voices, languages, formats, and prices. This endpoint provides all necessary details to choose the right voice for your project. You can also view voices in your dashboard.

First request

curl

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

Authentication is handled via a single active Bearer token per account. You generate this key on the /get-api-key/ page after signing in with Google or email. The token follows the standard tts-... prefix format and is used in every request header.

Generating Your Key

Generating Your Key

Access your dashboard at /get-api-key/ to view your current key and usage stats. The page displays your balance, characters remaining, and a ready-to-use curl example for immediate testing.

Bearer Token Format

Bearer Token Format

Include your key in the Authorization header as Bearer tts-<your-key>. This standard format ensures compatibility with the OpenAI SDKs and any standard HTTP client. Ensure no extra spaces are included in the token string.

Key Rotation

You can issue a new key at any time from your dashboard. The old key stops working immediately, ensuring only one active token exists per account. This is useful if you suspect a key has been exposed.

First Request with Curl

Sound wave illustration for: First Request with Curl

Use cURL to send your first synthesis request directly to the API. This method requires no external libraries, making it ideal for quick validation of your key and voice selection before integrating into your application code.

Basic POST Request

Send a JSON payload to the speech endpoint. Ensure you include your Bearer token in the Authorization header. The request body must contain the text input, selected voice, and desired output format.

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

Required Fields

Your request must specify a model (tts-1 or tts-1-hd), the input text (max 4096 characters), and a voice preset. While the language is optional, setting it explicitly prevents incorrect auto-detection for non-English Latin text.

  • model: "tts-1" or "tts-1-hd"
  • input: your text string
  • voice: e.g., "aria", "nova", or "felix"
  • response_format: mp3, wav, opus, flac, or pcm

Response Handling

A successful response returns the audio file directly in the body with the specified content type. If synthesis fails, the API returns an error JSON without charging your account, ensuring you can debug issues without cost.

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

To use the OpenAI SDK, simply point your base_url to https://api.suckbetth.com/v1 and supply your tts-... key. The request shape matches the official speech endpoint exactly, so you can swap providers without changing your code logic.

Changing Base URL

Configure your SDK client to use the SuckBetth base URL. This allows you to leverage familiar libraries while routing requests through our infrastructure. No custom client is required; standard HTTP headers handle authentication.

SDK Compatibility

The API mirrors the OpenAI speech endpoint structure. Official OpenAI SDKs work seamlessly by adjusting the base URL. You do not need a proprietary client; standard libraries handle the JSON body and response parsing.

Code Examples

Initialize your client with the new base URL and your Bearer token. Pass standard parameters like model, voice, and input. The response returns the audio file directly, just as you would expect from the reference implementation.

  • Set base_url to https://api.suckbetth.com/v1
  • Use Authorization: Bearer tts-... header
  • Pass model, voice, and input in JSON body

Endpoints Overview

Sound wave illustration for: Endpoints Overview

The API exposes three primary endpoints for integration: speech synthesis, voice metadata, and model details. Each endpoint serves a distinct purpose in the workflow, from generating audio to verifying available voices.

All endpoints use standard HTTP methods and return JSON or binary data. Authentication is required via the Bearer token in the Authorization header for every request.

Speech Endpoint

The core endpoint for generating audio files. Send a POST request to /v1/audio/speech with your text and voice parameters. The API returns the audio file directly in the response body.

Use this endpoint for all text-to-speech conversions. It supports multiple response formats and speed adjustments to fit your application's needs.

  • Endpoint: POST /v1/audio/speech
  • Returns: Audio file (mp3, wav, opus, flac, pcm)
  • Body: JSON with model, input, voice, speed

Voices Endpoint

Retrieve a list of all available voices, their associated languages, and supported formats. This endpoint helps you discover the 8 presets and 23 languages before making synthesis requests.

Use this to dynamically populate your UI's voice selection dropdown or to verify language support for a specific text input.

  • Endpoint: GET /v1/voices
  • Returns: List of voices with metadata
  • Includes: Voice ID, name, languages, formats

Models Endpoint

Get details about the available TTS models, including their capabilities and pricing tiers. This endpoint confirms the two models: 'tts-1' and 'tts-1-hd', which share the same engine and price.

Use this endpoint to ensure your application is using the correct model identifier for your desired quality level.

  • Endpoint: GET /v1/models
  • Returns: Model details and pricing
  • Models: tts-1, tts-1-hd

Request Parameters

Sound wave illustration for: Request Parameters

Configure the synthesis behavior by selecting a model, voice, and speed. The model field accepts either "tts-1" or "tts-1-hd"; both use the same engine and pricing. You must specify a voice from the eight available presets and can optionally set a speed between 0.25 and 4.0.

Model Selection

Choose between "tts-1" and "tts-1-hd" based on your quality needs. Both models run on the same engine and incur the same charge per character, so your choice affects audio fidelity but not cost or performance.

Voice Selection

Select from eight distinct presets ranging from warm narrators to energetic promo voices. Each voice can speak any of the 23 supported languages, though you should set the language field for non-English Latin script text to ensure accurate synthesis.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Speed Adjustment

Adjust the playback speed using the speed parameter, which accepts values from 0.25 to 4.0. This allows you to fine-tune the delivery for different content types, from slow storytelling to rapid-fire information.

Request Parameters

Response Formats

Sound wave illustration for: Response Formats

The API returns audio files in the format you specify, allowing you to choose the best balance between file size and quality for your project. You define the output type via the response_format parameter in your request.

Each format serves different use cases, from web playback to high-fidelity editing. All generated files include an inaudible synthetic watermark to identify them as AI-generated speech.

MP3 Output

MP3 is the default format, offering a good balance between audio quality and file size. It is ideal for web players and mobile applications where bandwidth efficiency matters.

This format supports standard bitrates and works seamlessly with most media libraries and frameworks.

  • Default format for most integrations

WAV Output

WAV provides uncompressed, high-quality audio suitable for professional editing or archival purposes. It preserves the full fidelity of the synthesis engine without data loss.

Use this format if you need to process the audio further with other tools that require raw audio data.

  • Uncompressed audio for editing

Other Formats

We also support Opus, FLAC, and PCM. Opus offers high-quality compression at low bitrates, suitable for voice-over-IP or streaming scenarios. FLAC provides lossless compression for storage efficiency.

PCM returns raw audio data, useful for specific hardware integrations or custom processing pipelines.

  • Opus: efficient streaming
  • FLAC: lossless compression
  • PCM: raw audio data

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a limit of 60 requests per minute for active keys. This throughput is designed to handle standard indie development workflows.

Requests Per Minute

Once your account is funded, you can send up to 60 requests per minute. This limit applies per API key, so ensure you are using a single active key for your primary integration.

Pre-Top-Up Limits

Accounts that have not yet topped up are restricted to 10 requests per minute. This lower limit allows you to test the free trial credit ($0.50) without hitting the cap immediately during development.

Queue Behavior

Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. This means response times can vary slightly depending on current server load, though typical speed remains close to real-time.

Error Handling

Sound wave illustration for: Error Handling

When synthesis fails, you get a clear error code, not a silent drop. Failed requests are free: if the engine can’t produce audio, the charge is returned in full. This keeps your budget predictable even when inputs are tricky or the queue is long.

Use the error message to adjust your request. If you hit a character limit, split the text into parts of up to 4096 characters and join the audio files. If the voice is unsupported, check the voices endpoint. Keep logs of request IDs to track billing discrepancies easily.

Common Error Codes

We return standard HTTP status codes. A 4xx error usually means bad input, like invalid JSON or an unknown voice ID. A 5xx error indicates a temporary server issue, often due to high load. Wait a few seconds and retry; requests are processed sequentially, so delays are normal under peak usage.

  • 400 Bad Request: Invalid JSON or missing required fields.
  • 401 Unauthorized: Expired or incorrect Bearer token.
  • 429 Too Many Requests: Exceeded 60 requests per minute limit.
  • 503 Service Unavailable: Temporary queue congestion; retry with exponential backoff.

Refund Process

If a request fails to generate audio, the charge is automatically reversed. You don’t need to submit a ticket. Check your balance dashboard to confirm the refund appears within minutes. Failed requests don’t count against your character limit, ensuring you only pay for usable audio.

Debugging Requests

Always log the request ID returned in the response headers. If audio is missing or corrupted, share this ID with support via email. We can trace the exact input and engine state. Ensure your input field stays under 4096 characters to avoid truncation errors.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. It works well for e-learning modules, audiobook snippets, or automated notifications where full real-time interaction isn't critical.

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. IETF RFC 7845: Ogg Opus
  3. curl documentation
  4. OpenAI API reference: create speech
  5. Python documentation
  6. Creative Commons Attribution 4.0
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. LibriVox public-domain audiobooks
  9. Node.js documentation
  10. openai-node on GitHub
  11. Tether (USDT)
  12. openai-python on GitHub

More on this site