Speech API: Text-to-Speech and Transcription (TTS/STT)

Request parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The TTS model. See available models below.

Example:<tts-model>

inputstringRequired

Text to synthesize. Billing is based on character count.

Example:Hello, this is a ZeroFA text-to-speech test.

voicestringOptional

The voice name depends on the model, such as Cherry for Qwen-TTS or alloy for OpenAI.

Example:Cherry

response_formatstringOptional

Output format: mp3, opus, aac, flac, wav, or pcm. Some upstreams use a fixed format.

Example:mp3

speednumberOptional

Speech speed. Supported by some upstreams only.

Example:1.0

Billing model

Billed by input character count, not duration or tokens. Failed requests are not charged.

Speech to text (STT)

POST/v1/audio/transcriptions

Upload an audio file with multipart and receive a transcript, billed by audio duration. response_format supports json, text, and verbose_json. Use paraformer-realtime-v2 for Paraformer real-time speech recognition.

Transcription · curl

curl https://zerofa.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=paraformer-realtime-v2" \
  -F "file=@audio.wav" \
  -F "response_format=json"

Real-time transcription (WebSocket)

GET/v1/audio/transcriptions/realtime

Send PCM16 mono binary audio frames after connecting. The server emits transcript.delta and transcript.completed events, then session.completed after input_audio_buffer.commit.

The handshake must include the Authorization header. max_duration_seconds defaults to 60 and is capped at 600. API-key calls reserve the maximum session cost and settle only actual seconds. Native browser WebSocket cannot set this header, so connect from your backend for now.

Real-time transcription · Python

import json
import time
import websocket

url = (
    "wss://zerofa.ai/v1/audio/transcriptions/realtime"
    "?model=paraformer-realtime-v2&format=pcm"
    "&sample_rate=16000&language=zh&max_duration_seconds=60"
)
ws = websocket.create_connection(
    url,
    header=["Authorization: Bearer sk-zerofa-xxx"],
    timeout=90,
)
print(json.loads(ws.recv()))  # session.created

with open("audio.pcm", "rb") as audio:
    while chunk := audio.read(3200):  # 100ms PCM16 mono 16kHz
        ws.send_binary(chunk)
        time.sleep(0.1)

ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
while True:
    event = json.loads(ws.recv())
    print(event)
    if event["type"] in {"session.completed", "error"}:
        break
ws.close()

Available models

See TTS models in the Model Catalog and filter for Audio. The model in the sample is a placeholder. If no matching model is listed, TTS is not currently available.

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

curl https://zerofa.ai/v1/audio/speech \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<tts-model>",
    "input": "Hello, this is a ZeroFA text-to-speech test.",
    "voice": "Cherry"
  }' \
  --output speech.wav

The response is binary audio such as audio/wav or audio/mpeg, not JSON. Write it directly to a file or play it.

Request parameters

Header parameters

AuthorizationstringRequired

API key in the format Bearer <key>.

Example:Bearer sk-zerofa-xxx

Content-TypestringRequired

Example:application/json

Body parametersapplication/json

modelstringRequired

The TTS model. See available models below.

Example:<tts-model>

inputstringRequired

Text to synthesize. Billing is based on character count.

Example:Hello, this is a ZeroFA text-to-speech test.

voicestringOptional

The voice name depends on the model, such as Cherry for Qwen-TTS or alloy for OpenAI.

Example:Cherry

response_formatstringOptional

Output format: mp3, opus, aac, flac, wav, or pcm. Some upstreams use a fixed format.

Example:mp3

speednumberOptional

Speech speed. Supported by some upstreams only.

Example:1.0

Speech to text (STT)

POST/v1/audio/transcriptions

Transcription · curl

curl https://zerofa.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=paraformer-realtime-v2" \
  -F "file=@audio.wav" \
  -F "response_format=json"

Real-time transcription (WebSocket)

GET/v1/audio/transcriptions/realtime

Send PCM16 mono binary audio frames after connecting. The server emits transcript.delta and transcript.completed events, then session.completed after input_audio_buffer.commit.

Real-time transcription · Python

import json
import time
import websocket

url = (
    "wss://zerofa.ai/v1/audio/transcriptions/realtime"
    "?model=paraformer-realtime-v2&format=pcm"
    "&sample_rate=16000&language=zh&max_duration_seconds=60"
)
ws = websocket.create_connection(
    url,
    header=["Authorization: Bearer sk-zerofa-xxx"],
    timeout=90,
)
print(json.loads(ws.recv()))  # session.created

with open("audio.pcm", "rb") as audio:
    while chunk := audio.read(3200):  # 100ms PCM16 mono 16kHz
        ws.send_binary(chunk)
        time.sleep(0.1)

ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
while True:
    event = json.loads(ws.recv())
    print(event)
    if event["type"] in {"session.completed", "error"}:
        break
ws.close()

Request and response bodies

Use the examples below to verify the request and response structures. To send a request, select Debug at the top of the page.

curl https://zerofa.ai/v1/audio/speech \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<tts-model>",
    "input": "Hello, this is a ZeroFA text-to-speech test.",
    "voice": "Cherry"
  }' \
  --output speech.wav

The response is binary audio such as audio/wav or audio/mpeg, not JSON. Write it directly to a file or play it.

Text to speech (TTS)

Request parameters

Billing model

Speech to text (STT)

Real-time transcription (WebSocket)

Available models

Request and response bodies

Text to speech (TTS)

Request parameters

Billing model

Speech to text (STT)

Real-time transcription (WebSocket)

Available models

Request and response bodies