Overview

Byteaudio generates natural-sounding speech from text using BytePlus' seed-audio-1.0 TTS engine. Requests are submitted to /api/v1/task and processed asynchronously — poll /api/v1/task/{task_id} until status becomes completed, then download the audio from the returned URL.

Typical end-to-end latency is 5–20 seconds depending on text length. Output is delivered as a downloadable audio file (default wav).

Currently available models

Model	Task type	Notes
`byteaudio`	`seed-audio-1.0`	BytePlus Seed Audio 1.0 — text-to-speech with optional voice cloning from a reference sample

Pricing

Billing is by output audio duration:

Metric	Rate
Output audio	$0.002/ seco n d (\approx$ 0.12 / minute)

Duration is rounded up to the nearest second and capped at 120 seconds per request (matching the upstream output ceiling).

Failed requests (validation error, upstream rejection, content moderation) refund frozen credits in full — you are only charged for successfully returned audio.

At submission time we freeze a conservative estimate based on your input length + requested speech_rate. On success, the difference between the estimate and the real duration is settled automatically (refund if over-estimated, additional charge if under-estimated).

Parameters

text (required)

The text to be synthesized. Up to 2048 characters (unicode-aware — punctuation, whitespace, emoji all count). Trimmed whitespace on both ends. Empty text is rejected.

format

Output audio container / codec. Accepted values: wav (default), mp3, pcm, ogg_opus.

sample_rate

Output audio sample rate in Hz. Accepted values: 8000, 16000, 24000 (default), 32000, 44100, 48000. Higher rates produce larger files without noticeable quality gain for speech.

speech_rate

Integer speech speed offset. Range -50 to 100, default 0.

0 — normal speed (1.0×)

100 — 2.0× speed (shorter output)

-50 — 0.5× speed (longer output)

Values outside the range are silently clamped.

pitch_rate

Integer pitch offset in semitones. Range -12 to 12, default 0. Values outside the range are silently clamped.

loudness_rate

Integer loudness offset. Range -50 to 100, default 0.

0 — normal loudness

100 — approximately 2.0× loudness

-50 — approximately 0.5× loudness

Values outside the range are silently clamped.

references (optional)

An array of reference resources for voice cloning or voice / style guidance. Each entry sets exactly one of the following fields — mixing fields in a single entry is rejected.

Audio references (up to 3 per request)

Field	Description
`speaker`	Preset voice ID from the BytePlus Doubao / Seed Audio voice catalog
`audio_data`	Base64-encoded reference audio sample, up to 10 MB decoded (`wav` / `mp3` / `pcm` / `ogg_opus`); optional `data:` URI prefix supported
`audio_url`	Publicly accessible HTTPS URL to a reference audio sample. ≤ 30 seconds, ≤ 10 MB

When supplying multiple audio references, use @Audio1, @Audio2, @Audio3 markers inside your text to switch between voices at word / sentence boundaries.

Image references (up to 1 per request)

Field	Description
`image_data`	Base64-encoded reference image, up to 10 MB decoded (`jpeg` / `png` / `webp`); optional `data:` URI prefix supported
`image_url`	Publicly accessible HTTPS URL to a reference image, ≤ 10 MB

Rules

Audio and image references cannot be mixed in the same request.

Each reference entry must set exactly one of the five fields above (setting zero or two+ fields is rejected).

Inline audio_data / image_data must be under 10 MB after base64 decoding.

Content moderation

BytePlus applies content moderation to both input text and the generated audio. Rejected submissions surface a clear error message from the upstream (for example: prohibited content, disallowed voice, invalid reference audio) and your frozen credits are refunded.

Common rejection reasons:

Sensitive / prohibited text content

Reference audio longer than the 30-second limit

Reference audio containing prohibited content

Requesting a preset voice you are not entitled to use

Response

Byteaudio is asynchronous. The initial POST /api/v1/task returns immediately with status: pending. Poll GET /api/v1/task/{task_id} until status becomes completed or failed.

On success, output.audio_url points to a temporary, publicly downloadable URL hosted on our storage. Download the file promptly — the URL is intended for near-term retrieval, not long-term hosting.

Tips

Prefer wav for downstream processing and mp3 for delivery to end users.

Keep text under a few hundred characters per request for lowest latency; longer input synthesizes at roughly 8× real-time.

For voice cloning, provide 5–10 seconds of clean reference audio via audio_url.

Use @AudioN markers in text when providing multiple audio references.

Request

Header Params

Body Params application/json

Examples

basic text-to-speech (defaults)custom rate / pitch / formatvoice cloning from a reference audio URL

{
    "model": "byteaudio",
    "task_type": "seed-audio-1.0",
    "input": {
        "text": "Hello from PiAPI. This is a byteaudio text-to-speech smoke test."
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200

application/json

Bodyapplication/json

Example

{
    "code": 200,
    "data": {
        "task_id": "c2eb9416-8ac5-4da8-a933-51626a699fc2",
        "model": "byteaudio",
        "task_type": "seed-audio-1.0",
        "status": "completed",
        "config": {
            "service_mode": "",
            "webhook_config": {
                "endpoint": "",
                "secret": ""
            }
        },
        "input": {
            "text": "Hello from PiAPI. This is a byteaudio text-to-speech smoke test.",
            "format": "mp3",
            "sample_rate": 24000
        },
        "output": {
            "audio_url": "https://img.theapi.app/temp/b04f4d2c-8e8e-4dc9-9fee-e408c38b9b1c.mp3",
            "duration": 5
        },
        "meta": {
            "created_at": "2026-07-08T02:53:43.256458815Z",
            "started_at": "2026-07-08T02:53:43.982496073Z",
            "ended_at": "2026-07-08T02:53:56.703711725Z",
            "usage": {
                "type": "point",
                "frozen": 0,
                "consume": 100000
            },
            "is_using_private_pool": false
        },
        "detail": null,
        "logs": [],
        "error": {
            "code": 0,
            "raw_message": "",
            "message": "",
            "detail": null
        }
    },
    "message": "success"
}

Seed-audio

Overview#

Currently available models#

Pricing#

Parameters#

text (required)#

format#

sample_rate#

speech_rate#

pitch_rate#

loudness_rate#

references (optional)#

Audio references (up to 3 per request)#

Image references (up to 1 per request)#

Rules#

Content moderation#

Response#

Tips#