beatraDocs

Text-to-speech

POST
/v1/audio/speech

Request Body

application/jsonRequired
metadataMetadata

Caller-supplied metadata; ≤16 keys, key ≤64 chars, value ≤512 chars

callback_urlCallback Url

HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state

callback_signing_key_idCallback Signing Key Id

Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided.

model_optionsModel Options

Per-model-family passthrough options; opaque to the platform, validated per model

voice
Required
Voice

Opaque Beatra voice_id (preset or cloned)

input
Required
Input

Text to synthesize. It may contain speech markup such as {pause 0.5}, {laugh}, {pron 行 hang2} or {sub W3C 万维网联盟}; read the vocabulary and limits from the model card (beatra.models.list).

Minimum length: 1Maximum length: 50000
modelModel

TTS model; 'auto' picks a model compatible with the voice

Default: "auto"Value in: "auto" | "minimax-speech-2.8-hd" | "minimax-speech-2.8-turbo" | "doubao-seed-tts-2.0"
languageLanguage

Optional BCP-47 language tag, for example zh-CN, yue-HK, or en-US. 'auto' explicitly asks the engine to detect the spoken language. Read supported_languages from the selected model's catalog card. When omitted, the voice or provider chooses the language.

formatFormat
Default: "mp3"Value in: "mp3" | "wav" | "flac" | "opus" | "pcm"
sample_rateSample Rate
speedSpeed
Default: 1Minimum: 0.5Maximum: 2
volumeVolume
Default: 1Maximum: 10
pitchPitch

Pitch adjustment from -1 to 1: 0 keeps the voice's original pitch, -1 is the lowest and 1 the highest the selected model supports. Use decimals such as 0.25 or -0.5 for subtle tuning.

Default: 0Minimum: -1Maximum: 1
emotionEmotion

Provider-neutral discrete speaking emotion

subtitle_enableSubtitle Enable

Request sentence-level subtitles with the audio. Subtitles are free; when present, output.subtitles carries the subtitle file URL and format.

Default: false
directionDirection

Optional natural-language performance direction for the whole request, for example '像在耳边说悄悄话一样，轻声地说' or 'read it like breaking news'. Models and voices that follow it list direction under controls on their model card (with direction_max_characters); anywhere else it is ignored with an option_ignored warning. Effects vary with the voice and the text and are not a guarantee of intensity.

previous_textPrevious Text

Optional text that comes right before this clip, for example the previous line of a dialogue or the previous paragraph, so separate calls keep a continuous tone. It is never spoken and never billed; any length is accepted and only its end is used (previous_text_tail_characters on the model card). Models and voices that do not use it ignore it with an option_ignored warning.

Header Parameters

X-Request-Idstring

Optional client request id echoed in the response.

Idempotency-Key
Required
Idempotency-Key
Minimum length: 1Maximum length: 128
Authorization
Required
string

Bearer API key.

curl -X POST "https://api.beatra.ai/v1/audio/speech" \
  -H "X-Request-Id: string" \
  -H "Idempotency-Key: string" \
  -H "Authorization: string" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "callback_url": "string",
    "callback_signing_key_id": "string",
    "model_options": {},
    "voice": "string",
    "input": "string",
    "model": "auto",
    "language": "string",
    "format": "mp3",
    "sample_rate": 8000,
    "speed": 1,
    "volume": 1,
    "pitch": 0,
    "emotion": "happy",
    "subtitle_enable": false,
    "direction": "string",
    "previous_text": "string"
  }'

Task accepted

{
  "object": "task",
  "task_id": "string",
  "status": "queued",
  "capability": "string",
  "workload_type": "model",
  "model": "string",
  "resolved_model": "string",
  "model_selection_reason": null,
  "social": {
    "platform": "string",
    "operation_key": "string",
    "operation_name": "string",
    "schema_hash": "string"
  },
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "input": {},
  "progress": {
    "percent": 100,
    "stage": "string",
    "message": "string"
  },
  "output": {},
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "error": {
    "code": "string",
    "type": "string",
    "message": "string",
    "retryable": true,
    "param": "string",
    "details": {},
    "request_id": "string"
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_tokens": 0,
    "cache_creation_tokens": 0,
    "reasoning_tokens": 0,
    "image_count": 0,
    "image_pixels": 0,
    "video_seconds": 0,
    "input_video_seconds": 0,
    "output_video_seconds": 0,
    "audio_seconds": 0,
    "characters": 0,
    "lines": [
      {
        "meter": "string",
        "quantity": "string",
        "unit": "string",
        "billed_amount_credits": "string"
      }
    ],
    "credits": "string"
  },
  "billing": {
    "charged_credits": "string",
    "refunded_credits": "string",
    "granted_credits": "string",
    "grant_source": "string",
    "net_charged_credits": "string"
  },
  "callback": {
    "url": "string",
    "status": "pending",
    "attempt_count": 0,
    "delivered_at": "2019-08-24T14:15:22Z",
    "last_error": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "cancel_requested_at": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "cancel": "string",
    "assets": "string"
  }
}

Last updated