beatra文档

用 AI 导演准备配音稿

创建一个异步的 AI 导演任务：读懂原文和可选的要求，按目标声音和模型写好情绪、表演、音效、停顿和读音，返回一份可以直接合成的配音稿，不改动原文；没有指定声音或模型时会推荐一个，并给出备选，每个都带名字、试听链接和理由。把每一稿的 `synthesis` 原样作为 `POST /v1/audio/speech` 的请求体；`synthesis` 为 `null` 的稿子不能直接合成。完成后按实际输入、输出和推理 token 计费；提交时，余额需不低于这段文字的预估费用（按能力目录的每千字预估折算，不足 1,000 字按 1,000 字计），本账号如有另一个进行中的 AI 导演任务，还要加上它的预估；每个账号最多同时进行 2 个 AI 导演任务。`directed` 为 `false`（AI 导演没能完成演绎），或复用了同一段文字之前的理解时，不收费。

下方的接口说明（参数、请求和响应）是英文原文，字段名与接口完全一致。

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"
  }
}

最后更新