beatraDocs

Prepare a speech script with the AI Director

Creates an asynchronous AI Director task. The AI Director reads the text and optional instructions, then returns a script that is ready to synthesize, in Beatra speech markup tailored to the target voice and model: emotion, performance, sound effects, pauses and pronunciation. It never changes the words. Without a voice or model it recommends one, with alternatives, each with a name, a preview link and a reason. Send each script's synthesis object, unchanged, as the body of POST /v1/audio/speech; a script whose synthesis is null cannot be synthesized as is. Charged after completion from actual input, output and reasoning tokens. To submit a text, the balance must cover its estimate (the catalog's estimate_per_1000_characters_credits for its length, counting at least 1,000 characters) plus that of any other AI Director task in progress on the account. An account runs at most 2 AI Director tasks at a time. Nothing is charged when the AI Director could not direct the text (directed is false) or reuses an earlier reading of the same text.

POST
/v1/audio/speech/scripts

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.

input
Required
Input

Text to perform, in any supported language, 1 to 50,000 characters. It may already contain Beatra speech markup such as {pause 0.5} or {pron 行 hang2}; the AI Director keeps it and only adds to it. The words themselves are never changed.

Minimum length: 1Maximum length: 50000
instructionsInstructions

Optional requirements in natural language, in any language, up to 2,000 characters, for example "a bit suspenseful, whisper the last line". Without them the AI Director performs the text by its meaning.

voiceVoice

Optional voice to perform for: a preset voice or one of your own cloned voices. Same meaning as voice in POST /v1/audio/speech. Omit it to let the AI Director recommend a voice.

modelModel

Optional speech model to perform for, with the same values and defaults as model in POST /v1/audio/speech. auto or omitted: resolved from the voice, or recommended together with the voice.

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

Language of the input as a BCP-47 tag. Usually omit it (auto, the default): the language is detected. Send it only when the user names the language or a dialect the text cannot show, such as Cantonese (yue).

Default: "auto"Minimum length: 2Maximum length: 32
contextAny properties in SpeechScriptContext

Optional, advanced: the text around the input when a long text is directed in parts, used only to understand the tone. It is not annotated, read aloud or returned. The end of before is also suggested as previous_text when the target model supports it.

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/scripts" \
  -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",
    "input": "string",
    "instructions": "string",
    "voice": "string",
    "model": "auto",
    "language": "auto",
    "context": {
      "before": "string",
      "after": "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