MCP 工具参考
Beatra MCP 服务器上的全部工具，由工具定义生成：每个工具的用途、参数、返回值，以及是否扣积分。
Beatra MCP 服务器（https://mcp.beatra.cn/mcp）提供下面这些工具。本页在每次发布文档时由 Beatra MCP 服务的工具列表生成。实时清单见 GET https://mcp.beatra.cn/tools，或在 MCP 端点调用 tools/list。
装好 Beatra Skill 后，它连接这个服务器，替你的智能体调用这些工具；只需在浏览器里登录一次。安装方法见安装 Beatra Skill。调用前想知道它会做什么，查本页；调用出错时，到排错指南按错误码查原因和处理办法。
参数说明和工具说明取自工具定义，保留英文原文；参数名照原样传入。
每个工具的说明项
| 项目 | 含义 |
|---|---|
| 积分 | 调用成功后是否消耗 Beatra 积分。生成类价格以 beatra.models.list 为准，社交数据价格以 beatra.social.tools.get 为准。 |
| 执行方式 | 异步任务，用 beatra.tasks.get 轮询；或者直接返回结果。 |
| 作用 | 只读取数据、向账号写入新数据，还是改变进行中的工作。 |
| 可重复调用 | 完全相同的调用重复发出时，效果是否不变。任务类工具用 client_request_id 保证这一点。 |
| 权限范围 | 登录授权必须包含的权限。缺少时返回 insufficient_scope。 |
图片
beatra.images.generate
根据文字描述生成 1 到 4 张图片。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、images:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2、image-01-live、wan2.7-image-pro、wan2.7-image、qwen-image-3.0-pro、qwen-image-3.0、qwen-image-2.0-pro、qwen-image-2.0 |
prompt | string | 是 | Required prompt containing at least one non-whitespace character. 限制：长度 ≥ 1 |
count | integer | 否 | Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. 默认值： 1限制：1–4 |
canvas | ImagePresetCanvas | ImageTargetCanvas | 否 | Desired output canvas. Presets are quality tiers, and target dimensions may be normalized or vary; inspect output images for actual dimensions. 默认值： {"type":"preset","tier":"2K","aspect":"16:9"} |
seed | integer | 否 | Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. 限制：0–2147483647 |
negative_prompt | string | 否 | Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. |
enhance_prompt | boolean | 否 | Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; an explicit boolean constrains model eligibility. |
palette | array of ImagePaletteColor | 否 | Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. 限制：项数 3–10 |
output_relationship | ImageOutputRelationship | 否 | Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. 默认值： independent可选值： independent、sequence |
reasoning | boolean | 否 | Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate one to four images from text without source images. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.images.transform
以 1 到 4 张按顺序排列的参考图加提示词，生成新图片。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、images:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2、image-01-live、wan2.7-image-pro、wan2.7-image、qwen-image-3.0-pro、qwen-image-3.0、qwen-image-2.0-pro、qwen-image-2.0 |
prompt | string | 是 | Required prompt containing at least one non-whitespace character. 限制：长度 ≥ 1 |
count | integer | 否 | Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. 默认值： 1限制：1–4 |
canvas | ImageTransformPresetCanvas | ImageTargetCanvas | 否 | Desired output canvas. Preset source inherits the last input image's ratio; the omitted default is 2K at 16:9.默认值： {"type":"preset","tier":"2K","aspect":"16:9"} |
seed | integer | 否 | Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. 限制：0–2147483647 |
negative_prompt | string | 否 | Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. |
enhance_prompt | boolean | 否 | Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; an explicit boolean constrains model eligibility. |
palette | array of ImagePaletteColor | 否 | Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. 限制：项数 3–10 |
images | array of ImageMediaInputUrl | ImageMediaInputArtifact | ImageMediaInputDataUri | 是 | Ordered artifact, HTTPS URL, or data URI references. 限制：项数 1–4 |
output_relationship | ImageOutputRelationship | 否 | Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. 默认值： independent可选值： independent、sequence |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Transform one to four ordered reference images with a prompt; when canvas aspect is source, the last reference anchors the ratio. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.images.edit
按指令修改一张底图，可以附加参考图，也可以指定要修改的区域。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、images:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2、image-01-live、wan2.7-image-pro、wan2.7-image、qwen-image-3.0-pro、qwen-image-3.0、qwen-image-2.0-pro、qwen-image-2.0 |
prompt | string | 是 | Required prompt containing at least one non-whitespace character. 限制：长度 ≥ 1 |
count | integer | 否 | Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. 默认值： 1限制：1–4 |
canvas | ImageEditPresetCanvas | ImageTargetCanvas | 否 | Desired output canvas. The default is a 2K tier derived from the first base image's ratio; actual output dimensions remain authoritative. 默认值： {"type":"preset","tier":"2K","aspect":"source"} |
seed | integer | 否 | Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. 限制：0–2147483647 |
negative_prompt | string | 否 | Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. |
enhance_prompt | boolean | 否 | Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; an explicit boolean constrains model eligibility. |
palette | array of ImagePaletteColor | 否 | Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. 限制：项数 3–10 |
images | array of ImageMediaInputUrl | ImageMediaInputArtifact | ImageMediaInputDataUri | 是 | Ordered inputs; images[0] is the base and later entries are references. 限制：项数 1–4 |
edit_regions | array of ImageEditRegion | 否 | Flat normalized rectangles keyed by an input image_index. Runtime validation enforces cross-coordinate and collection relations. 限制：项数 1–8 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Edit images[0] as the base image; later images are ordered references and optional regions use normalized coordinates. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.images.understand
回答关于 1 到 8 张图片的问题。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、images:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、MiniMax-M3 |
prompt | string | 是 | Required question or instruction containing non-whitespace characters. 限制：长度 1–4000 |
images | array of MediaInputUrl | MediaInputArtifact | ImageUnderstandingDataUri | 是 | One through eight ordered image inputs. Each admitted image is billed once. 限制：项数 1–8 |
detail | string | 否 | Visual detail preference. It does not change Beatra's per-image price. 默认值： default可选值： default、low、high |
response_format | string | 否 | 可选值：text、json |
temperature | number | 否 | 限制：0–2 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Answer questions about one to eight ordered images, each limited to 10 MiB. Upload a local image with beatra.assets.upload first and pass it as an artifact; use data_uri only for very small images. Successful tasks cost 5 credits per admitted image; detail does not affect price. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
视频
beatra.videos.enhance_prompt
参考图片、视频或音频，把视频提示词改写得更完整。结果是改写后的文字。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | any | 否 | Compatibility input only. Its value and type are ignored in the first release; Beatra resolves the available prompt-enhancement model internally. 默认值： auto |
prompt | string | 是 | Required creative intent to expand into a production-ready video prompt. 限制：长度 1–7000 |
duration | integer | 是 | Target video duration in integer seconds. 限制：4–15 |
aspect_ratio | string | 是 | Target video aspect ratio. Text-only requests cannot use adaptive. 可选值： adaptive、21:9、16:9、4:3、1:1、3:4、9:16 |
first_frame | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional strict first-frame context image. |
last_frame | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional strict last-frame context image. |
references | array of VideoReference | 否 | Optional ordered image, video, or audio context. Reference mode and strict-frame mode are mutually exclusive. 限制：项数 ≤ 11 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Enhance a creative video prompt from optional image, video, or audio context. This creates an asynchronous text-only task and does not generate video. The model compatibility field is ignored. This asynchronous task consumes Beatra credits; successful completion is charged afterward from actual input and output tokens; failed or canceled tasks are not charged. Submit exactly once, then poll with beatra.tasks.get. Reuse client_request_id only for an identical retry.
beatra.videos.generate
根据文字描述生成视频；支持的模型可以加驱动音频。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、minimax-h3、wan3.0-video、wan3.0-video-prime、happyhorse-1.1-t2v、wan2.7-t2v、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | "auto" | 否 | Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
prompt | string | 是 | Required description of the video to generate without source image or video media. 限制：长度 1–20000 |
audio | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional driving audio for models that support audio-conditioned generation. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate from text when there is no source image or video. Supports optional driving audio on compatible models. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.animate
以一张图片作首帧生成视频，可以加驱动音频。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、minimax-h3、wan3.0-video、wan3.0-video-prime、happyhorse-1.1-i2v、wan2.7-i2v、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | "auto" | 否 | Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
prompt | string | 否 | Optional motion, scene, and camera instructions for animating the opening image. 限制：长度 ≤ 20000 |
image | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 是 | Required strict first-frame image; this is not a loose visual reference. |
driving_audio | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional driving audio. Supplying it requires a model that supports this control. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Animate a first-frame image, optionally with driving audio; use interpolate instead when both first and last frames are supplied. Call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.generate_from_references
根据按顺序排列的图片、视频和音频参考生成视频。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、minimax-h3、wan3.0-video、wan3.0-video-prime、happyhorse-1.1-r2v、wan2.7-r2v、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | "auto" | 否 | Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
prompt | string | 否 | Optional instructions describing how the ordered references should guide the output. 限制：长度 ≤ 20000 |
references | array of VideoReference | 是 | One to fifty ordered image, video, or audio references. Model-specific kind, count, duration, and combination limits still apply. 限制：项数 1–50 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate from ordered image, video, and audio references. Use animate for one strict opening image and interpolate for strict first and last frames. Call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.interpolate
生成以指定尾帧结束的视频，也可以同时指定首帧。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、minimax-h3、wan3.0-video、wan3.0-video-prime、wan2.7-i2v、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | "auto" | 否 | Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
prompt | string | 否 | Optional instructions for the motion ending at the required last frame. 限制：长度 ≤ 20000 |
first_frame | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional image that must be the video's first frame. Omit it for a last-frame-only request when the selected model advertises that input combination. |
last_frame | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 是 | Required image that must be the video's last frame. |
driving_audio | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | Optional driving audio. Supplying it requires a model that supports this control. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate toward a required last frame, optionally constrained by a first frame and driving audio. Use animate when only a first frame exists. Call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.edit
按指令修改一段已有视频，可以附加参考素材。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、wan3.0-video、wan3.0-video-prime、happyhorse-1.0-video-edit、wan2.7-videoedit、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | "auto" | 否 | Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
source_video | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 是 | Required video whose existing content will be edited. |
instruction | string | 是 | Required instruction describing changes to the source video. 限制：长度 1–20000 |
references | array of VideoReference | 否 | Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. 限制：项数 ≤ 49 |
audio_setting | string | 否 | Optional edit-audio policy: auto lets a compatible model choose, while origin requests preservation of source audio. 可选值： auto、origin |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Edit one source video by instruction, with optional multimodal references; do not use this to extend a clip. Input plus output duration may be billable. Call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.extend
在一段已有视频的前面或后面接着生成画面。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. 默认值： auto可选值： auto、wan3.0-video、wan3.0-video-prime、wan2.7-i2v、seedance-2、seedance-2-fast、seedance-2-mini、seedance-2.5 |
negative_prompt | string | 否 | Content or qualities to avoid when supported by the selected model. 限制：长度 ≤ 500 |
duration | integer | 是 | Required final returned-video duration in integer seconds. It must exceed the trusted source-video duration; model-specific admission may narrow the range. 限制：2–30 |
aspect_ratio | string | 否 | Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. 可选值： 16:9、9:16、1:1、4:3、3:4、4:5、5:4、21:9、9:21、adaptive |
resolution | string | 否 | Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. 可选值： 480p、720p、1080p、2k、4k |
seed | integer | 否 | 限制：0–2147483647 |
enhance_prompt | boolean | 否 | Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. |
watermark | boolean | 否 | Whether generated video should include the model watermark. |
generate_audio | boolean | 否 | Whether the selected model should generate synchronized audio. |
web_search | boolean | 否 | Whether the selected model may use web search during generation. |
return_last_frame | boolean | 否 | Whether to return the generated video's last frame as an image artifact. |
output_format | string | 否 | Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 可选值： mp4、mov |
video | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 是 | The single source video to continue. |
direction | string | 是 | Generate new content immediately before or after the source video's content. 可选值： before、after |
instruction | string | 是 | Required instruction describing how the source video should continue. 限制：长度 1–20000 |
references | array of VideoReference | 否 | Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. 限制：项数 ≤ 49 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate footage immediately before or after one source clip. Use edit to alter existing frames. Duration is a required integer final returned-video duration, must exceed the trusted source duration, and does not accept auto. Call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.compose
把你自己的视频片段拼成一个 MP4，可以加旁白、背景音乐和内嵌字幕。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
clips | array of ComposeClip | 是 | 限制：项数 1–12 |
narration | MediaInputArtifact | 否 | — |
music | ComposeMusic | 否 | — |
subtitles | array of ComposeSubtitle | 否 | 限制：项数 ≤ 200 |
canvas | string | 否 | 默认值：9:16可选值： 9:16、16:9、1:1、3:4 |
model | string | 否 | 默认值：auto可选值： auto、beatra-compose-v1 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Join your own video clips into one MP4 with optional narration, ducked music, and burned-in subtitles. Set keep_audio on a clip to keep that clip's own sound, such as a lip-synced presenter take; other clips are muted. This call does not consume Beatra credits. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.videos.understand
回答关于一段视频的问题。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、videos:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit or use 'auto' unless the user explicitly requests MiniMax-M3. 默认值： auto可选值： auto、MiniMax-M3 |
prompt | string | 是 | Required question or instruction containing non-whitespace characters. 限制：长度 1–32000 |
video | MediaInputUrl | MediaInputArtifact | VideoUnderstandingDataUri | 是 | The single video input. Beatra samples internally at 1 fps, 0.5 fps from 120 seconds, and 0.2 fps from 240 seconds. |
detail | string | 否 | Visual detail preference. It does not change Beatra's per-second price. 默认值： default可选值： default、low、high |
response_format | string | 否 | 可选值：text、json |
temperature | number | 否 | 限制：0–2 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Answer questions about one video limited to 50 MiB and 360 seconds. Upload a local video with beatra.assets.upload first and pass it as an artifact; use data_uri only for very small videos. Beatra samples at 1 fps, or 0.5 fps from 120s and 0.2 fps from 240s; successful tasks cost 0.4 credits per rounded-up admitted second and detail does not affect price. Omit model unless the user explicitly requests one; call beatra.models.list before model or cost comparisons. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
音乐
beatra.music.generate
根据描述生成音乐，可以附歌词或参考音频。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、music:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 否 | Omit unless the user requests a model. 默认值： auto可选值： auto、minimax-music-3.0、suno-6、suno-5.5、suno-v6 |
prompt | string | 是 | Style, mood, genre, and instrumentation. When lyrics are supplied (or Suno custom mode is on) this maps to the provider's style-conditioning field; otherwise it is the song description the model writes the song from. Either way it is not an instruction field: execution directives written here (for example "do not omit anything", "sing it verbatim", "make chapter three differ from chapter one") are not read as instructions and will not be obeyed. Put the words to be sung in lyrics, or set instrumental to true for a track with no vocals.限制：长度 1–2000 |
lyrics | string | 否 | Optional lyrics text. Must be omitted for instrumental music. 限制：长度 ≤ 5000 |
instrumental | boolean | 否 | When true, generate instrumental music without vocals. 默认值： false |
title | string | 否 | 限制：长度 ≤ 100 |
model_options | MusicModelOptions | 否 | Options grouped by public music model family. |
reference_audio | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 否 | — |
client_request_id | string | 是 | 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Generate music from a prompt, with optional lyrics or reference audio. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
语音
beatra.speech.prepare_script
把文本整理成按音色和模型标好情绪、停顿和读音的语音脚本，可以原样交给 beatra.speech.synthesize；也可以推荐音色。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、speech:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
input | string | 是 | 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. 限制：长度 1–50000 |
instructions | string | 否 | 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. 限制：长度 ≤ 2000 |
voice | string | 否 | Optional voice to perform for: a voice_id from beatra.voices.list, a preset or one of your own cloned voices. Same meaning as voice in beatra.speech.synthesize. Omit it to let the AI Director recommend a voice. |
model | string | 否 | Omit unless the user requests a model. Same values as model in beatra.speech.synthesize; auto or omitted: resolved from the voice, or recommended together with the voice. 默认值： auto可选值： auto、minimax-speech-2.8-hd、minimax-speech-2.8-turbo、doubao-seed-tts-2.0、elevenlabs-v4-turbo、elevenlabs-v4 |
language | string | 否 | 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). 默认值： auto限制：长度 2–32 |
context | 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. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Use before beatra.speech.synthesize to make speech sound natural and human. Beatra's AI Director reads the text and the user's optional instructions, then returns a script that is ready to synthesize, written in Beatra speech markup for the target voice and model: emotion, performance, sound effects, pauses and pronunciation. It never changes the words. Without voice or model it recommends one, with alternatives, each with a name, a preview link and a reason. Call beatra.speech.synthesize with each returned script's synthesis object as the arguments, unchanged, plus your own client_request_id; a script whose synthesis is null cannot be synthesized as is (read warnings). To try another voice within two days, call again with the same arguments, changing only voice (and model if needed): the earlier reading is reused and not charged again. This asynchronous task consumes Beatra credits: successful completion is charged afterward from actual tokens; nothing is charged when the result has directed false or reuses an earlier reading. To start, the balance must cover Beatra's estimate for the text (per 1,000 characters, counting at least 1,000) plus that of any other AI Director task in progress, also when an earlier reading is reused; an insufficient_balance refusal states the amount needed. An account runs at most 2 AI Director tasks at a time. Submit exactly once, then poll with beatra.tasks.get. Reuse client_request_id only for an identical retry.
beatra.speech.synthesize
用 Beatra 音色把文本合成为语音。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、speech:generate、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model_options | object | 否 | Per-model-family passthrough options; opaque to the platform, validated per model |
voice | string | 是 | Opaque beatra voice_id (preset or cloned) |
input | string | 是 | 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). Some models also accept inline emotion and performance markup, listed under script_markup on their card; other models skip it with a warning. Malformed markup is corrected or skipped with a markup_adjusted warning instead of failing the request. Some models accept fewer characters; read constraints.input_max_characters on the model card (ElevenLabs models: 10,000). 限制：长度 1–50000 |
model | string | 否 | Omit unless the user requests a model. 默认值： auto可选值： auto、minimax-speech-2.8-hd、minimax-speech-2.8-turbo、doubao-seed-tts-2.0、elevenlabs-v4-turbo、elevenlabs-v4 |
language | string | 否 | 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. 限制：长度 2–32 |
format | string | 否 | 默认值：mp3可选值： mp3、wav、flac、opus、pcm |
sample_rate | integer | 否 | 可选值：8000、16000、22050、24000、32000、44100 |
speed | number | 否 | 默认值：1限制：0.5–2 |
volume | number | 否 | 默认值：1限制：≤ 10、> 0 |
pitch | number | 否 | 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. 默认值： 0限制：-1–1 |
emotion | string | 否 | Provider-neutral discrete speaking emotion 可选值： happy、sad、angry、fearful、disgusted、surprised、calm、fluent |
subtitle_enable | boolean | 否 | Request sentence-level subtitles with the audio. Subtitles are free; when present, output.subtitles carries the subtitle file URL and format. 默认值： false |
direction | string | 否 | 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_text | string | 否 | 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. |
client_request_id | string | 是 | 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Synthesize speech using a Beatra voice ID. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry. The input accepts speech markup. Read the vocabulary and limits from the model card returned by beatra.models.list. beatra.speech.validate checks the input before you submit and does not charge credits.
beatra.speech.validate
提交前检查一次语音请求：解析标记、列出警告，并给出积分价格。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、speech:generate |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
voice | string | 是 | Opaque beatra voice_id (preset or cloned) |
input | string | 是 | 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). Some models also accept inline emotion and performance markup, listed under script_markup on their card; other models skip it with a warning. Malformed markup is corrected or skipped with a markup_adjusted warning instead of failing the request. Some models accept fewer characters; read constraints.input_max_characters on the model card (ElevenLabs models: 10,000). 限制：长度 1–50000 |
model | string | 否 | Model to check against (default auto) 默认值： auto可选值： auto、minimax-speech-2.8-hd、minimax-speech-2.8-turbo、doubao-seed-tts-2.0、elevenlabs-v4-turbo、elevenlabs-v4 |
language | string | 否 | BCP-47 language hint 限制：长度 2–32 |
format | string | 否 | Audio format the create call would use 默认值： mp3可选值： mp3、wav、flac、opus、pcm |
sample_rate | integer | 否 | Sample rate in Hz for the chosen format 可选值： 8000、16000、22050、24000、32000、44100 |
speed | number | 否 | Speaking rate (0.5 to 2.0) 默认值： 1限制：0.5–2 |
volume | number | 否 | Volume (0 to 10) 默认值： 1限制：≤ 10、> 0 |
pitch | number | 否 | Normalized pitch (-1.0 to 1.0) 默认值： 0限制：-1–1 |
emotion | string | 否 | Emotion preset for the whole request 可选值： happy、sad、angry、fearful、disgusted、surprised、calm、fluent |
subtitle_enable | boolean | 否 | Whether the create call would request subtitles 默认值： false |
direction | string | 否 | 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_text | string | 否 | 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. |
model_options | object | 否 | Expert provider options, same as the create call |
返回 McpSpeechValidateOutput：valid、warnings、weighted_characters、price_credits、execution、script_markup、limitations、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Check a speech request before paying for it: parse the markup, list warnings, count weighted characters, and return the credit price. This call does not create a task, charge credits, or call the speech engine. The markup vocabulary is on the model card from beatra.models.list.
音色
beatra.voices.clone
用一段干净的单人录音克隆音色，需用户先确认拥有这个声音的使用权。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、voices:write、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
model_options | object | 否 | Only for model doubao-voice-clone-2.0: {"doubao": {...}} with the model_options.doubao keys its clone card lists in controls. Ignored for every other model. |
sample | MediaInputUrl | MediaInputArtifact | MediaInputDataUri | 是 | Clean single-speaker voice sample (uploaded artifact or HTTPS URL), ~10s-5min |
prompt | VoiceClonePrompt | 否 | Optional short aligned excerpt: audio shorter than 8 seconds plus its verbatim transcript. Used only by models whose card sets prompt_accepted=true; other models ignore it and return an option_ignored warning. |
display_name | string | 是 | 限制：长度 1–255 |
model | string | 否 | Clone engine. Omit unless the user explicitly asks for a specific clone engine; 'auto' (the default) lets the platform choose. 默认值： auto可选值： auto、minimax-voice-clone、doubao-voice-clone-2.0、elevenlabs-voice-clone |
language | string | 否 | Optional BCP-47 language hint for the cloned voice 限制：长度 2–32 |
consent_attested | true | 是 | Caller asserts it has the rights to clone this voice. Recorded, not verified. |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Clone a voice from a clean single-speaker sample. With the default engine (omit model or use 'auto') the cloned voice is ready for speech as soon as the task succeeds. A few explicitly selected models need a separate paid activation before the voice can be used; the result explains the next step. Call only after the user explicitly confirms they have the rights to clone it, and set consent_attested=true. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
beatra.voices.activate
激活克隆结果要求激活的音色，需用户先同意报价。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、voices:write、wallet:spend、tasks:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
voice_id | string | 是 | The voice_id from the clone result. 限制：长度 1–64 |
confirmation_token | string | 否 | The confirmation_token from the clone result's activation.quote (or a later quote); valid for 24 hours. Omit it to get a new quote; nothing is charged. 限制：长度 1–1024 |
confirm_credits | integer | 否 | The quoted price_credits, repeated to confirm the user agreed to exactly that price. 限制：≥ 0 |
client_request_id | string | 是 | Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. 限制：长度 1–128 |
返回 VoiceActivateOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error、voice、charged_credits、quote
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Activate a cloned voice whose clone result says activation is required (status pending_activation). Voices that are already ready, including every MiniMax clone, every ElevenLabs clone, and every preset voice, never need this; calling it on them charges nothing and changes nothing. The clone result already carries the quote (activation.quote: price, terms, preview, confirmation_token). Only after the user explicitly agrees to the price and terms, call once with voice_id, confirmation_token and confirm_credits; this consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get; reuse the same client_request_id only for an identical retry. Called without confirmation_token (the token is gone or older than 24 hours), it returns a new quote and charges nothing.
beatra.voices.list
列出可用于语音合成的预设音色和克隆音色。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、voices:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
language | string | 否 | 限制：长度 ≤ 32 |
gender | string | 否 | 可选值：male、female、neutral |
category | string | 否 | 可选值：preset、cloned |
query | string | 否 | 限制：长度 ≤ 128 |
model | string | 否 | Compatible model id |
age_group | string | 否 | child, youth, adult, or senior |
voice_id | string | 否 | Exact voice_id 限制：长度 ≤ 64 |
limit | integer | 否 | Page size 默认值： 50限制：1–500 |
cursor | string | 否 | voice_id of the last voice on the previous page 限制：长度 ≤ 64 |
use_case | string | 否 | Voices tagged with this use case |
search | string | 否 | Case-insensitive text found in the display name or the persona 限制：长度 ≤ 64 |
status | string | 否 | Which voices to list: ready (default, usable for speech), pending_activation (cloned previews that need activation), expired, or any. 默认值： ready可选值： ready、pending_activation、expired、any |
返回 VoiceListOutput：voices、default_voice_id、error、next_cursor、total_count
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
List preset and tenant-owned voices available for speech synthesis. By default only voices ready for speech are listed; pass status to include cloned voices that are waiting for activation.
beatra.voices.update
重命名克隆音色，或把某个音色设为账号的默认音色。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、voices:write |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
voice_id | string | 是 | 限制：长度 1–64 |
display_name | string | 否 | New name for one of this account's cloned voices. 限制：长度 1–40 |
make_default | boolean | 否 | true makes this voice the account's default; false or omitted leaves the default as it is. Clearing the default is console-only. |
返回 VoiceUpdateOutput：voice_id、display_name、is_default、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Rename one of this account's cloned voices, or make a voice (cloned or preset) the account's default. Call only when the user asked for that change. This call is non-billable and cannot delete a voice; deleting happens in the Beatra console.
人像形象
beatra.avatars.list
列出为口播视频保存的人像形象，以及每个形象搭配的音色。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、artifacts:read |
参数
这个工具没有参数。
返回 AvatarListOutput：avatars、default_avatar_id、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
List the portraits this account saved as avatars for talking-presenter videos, the default first, each with its image artifact and paired voice. Pass image.artifact_id as the portrait to beatra.videos.animate after checking the image against the live model card. This call is read-only and does not charge.
beatra.avatars.save
把账号里的一张图片保存为有名字的人像形象，供以后的口播视频使用，需用户先确认人像授权。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、artifacts:write |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
artifact_id | string | 是 | An image artifact_id in this account, from beatra.assets.upload or an earlier task. 限制：长度 1–64 |
display_name | string | 是 | The name the user gave this avatar. 限制：长度 1–40 |
purpose | string | 否 | Optional use, such as 'course lecturer'. 限制：长度 ≤ 60 |
voice_id | string | 否 | Optional voice to pair with this avatar. 限制：长度 1–64 |
make_default | boolean | 否 | Also make this the account's default avatar. 默认值： false |
consent_attested | true | 是 | Set true only after the user confirmed the portrait consent sentence. |
consent_subject | string | 是 | self: the user is the person pictured. authorized_other: the user has that person's separate consent. 可选值： self、authorized_other |
返回 AvatarSaveOutput：avatar、default_avatar_id、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Save one image already in this account as a named avatar the user can reuse in later sessions. Call only after the user agreed to save it and confirmed the portrait consent sentence: they are the person pictured (consent_subject=self) or they have that person's separate consent (authorized_other). Saving the same image again updates and returns the same avatar. This call is non-billable and cannot delete anything.
公开社交数据
beatra.social.tools.search
按平台、关键词或能力类别搜索公开社交数据工具。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 否 | 限制：长度 ≤ 256 |
platform | string | 否 | 可选值：tiktok、douyin、xiaohongshu、instagram、youtube、twitter |
capability_family | string | 否 | 可选值：content、creator、comments、trends、captions |
limit | integer | 否 | 默认值：10限制：1–20 |
cursor | string | 否 | 限制：长度 ≤ 256 |
返回 SocialToolsSearchOutput：items、next_cursor、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Search public social data tools by platform, keyword, or capability_family. This call is not billable.
beatra.social.tools.get
查看一个公开社交数据工具的参数、schema_hash 和积分价格。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
operation_key | string | 是 | 限制：长度 1–128 |
返回 SocialToolsGetOutput：operation、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Read one public social data tool, including its arguments, schema_hash, and credit price. This call is not billable.
beatra.social.execute
以任务方式执行一次公开社交数据查询。
| 积分 | 消耗积分 |
|---|---|
| 执行方式 | 异步任务：用 beatra.tasks.get 轮询到结束 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、wallet:spend、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
operation_key | string | 是 | 限制：长度 1–128 |
schema_hash | string | 是 | — |
arguments | object | 否 | — |
client_request_id | string | 是 | Submit exactly once, then poll with beatra.tasks.get. 限制：长度 1–128 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Look up public social data and create a task. This billable call consumes Beatra credits and creates an asynchronous task. Submit exactly once, then poll with beatra.tasks.get. Reuse the same client_request_id only for an identical retry.
模型
beatra.models.list
列出某项能力当前可选的模型，以及实时的控制项、限制和积分价格。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
capability | string | 是 | Generation capability such as text_to_image. |
include_activation_required | boolean | 否 | Also list voice clone models that are not in the default list: models whose voices need a separate paid activation before use, and models that must be chosen explicitly and are never picked by auto. 默认值： false |
返回 ModelListOutput：account_offer、top_up、capability、default_model、auto、models、max_output_images、max_canvas_pixels、starting_credits、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
List models currently selectable for one Beatra generation capability, including live supported controls, constraints, customer credit prices, and billing basis.
capabilityis required and must be an exact generation capability from this tool's input schema enum. For image prices, select the pricing.options entry whose dimensions match the admitted output; Use before choosing or comparing a model or estimating cost; otherwise keep model=auto.
任务
beatra.tasks.list
列出这个连接最近创建的任务。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、tasks:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
cursor | string | 否 | — |
limit | integer | 否 | 默认值：10限制：1–50 |
status | string | 否 | 可选值：queued、running、succeeded、failed、canceled |
capability | string | 否 | — |
返回 TaskListOutput：items、next_cursor、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
List recent Beatra tasks created by this MCP connection.
beatra.tasks.get
查看这个连接创建的某个任务：状态、结果和扣费。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、tasks:read、artifacts:read |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_id | string | 是 | 限制：长度 ≥ 1 |
返回 TaskToolOutput：task_id、status、terminal、resolved_model、usage、billing、task、artifacts、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Read a Beatra task created by this MCP connection.
beatra.tasks.cancel
取消这个连接创建的任务。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 改变进行中的工作 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools、tasks:cancel |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_id | string | 是 | 限制：长度 ≥ 1 |
返回 TaskCancelOutput：task_id、status、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Cancel a task created by this MCP connection. In-flight work is canceled only when the remote stop is confirmed; a 409 means continue polling the same task.
积分
beatra.wallet.get
查看账号的积分余额，以及最近一批到期的积分。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
这个工具没有参数。
返回 WalletGetOutput：balance_credits、expiring_credits、non_expiring_credits、next_expiry_at、next_expiry_credits、topup_url、concurrent_task_limit、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Read the current Beatra credit balance for this account, including the next expiring batch. Also returns how many unfinished creations this account can keep at a time. This call is read-only and does not charge. It does not top up, change the wallet, or estimate a generation; use beatra.models.list for prices. On insufficient_balance, relay that error's message instead of calling this tool as a substitute. After the user says they have topped up, call this tool once before retrying: the balance_credits in an earlier refusal is the balance at that moment, not the current one.
beatra.wallet.ledger
按时间倒序列出积分明细：扣费、退款、充值和过期。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 只读 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
cursor | string | 否 | — |
limit | integer | 否 | 默认值：20限制：1–50 |
返回 WalletLedgerOutput：items、next_cursor、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
List this account's credit ledger newest first: charges, refunds, top-ups, and expiry. This call is read-only and does not charge. Page with the returned next_cursor. Ledger amounts are not a price estimate; use beatra.models.list before comparing models or quoting a generation.
上传
beatra.assets.upload
为本地图片、音频或视频文件申请一个短时有效的上传地址。上传完成后的响应会返回 artifact ID，其他工具用它引用这个文件。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 否：每次调用各自生效 |
| 权限范围 | mcp:tools、artifacts:write |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
filename | string | 否 | 限制：长度 1–255 |
mime_type | string | 是 | Exact media MIME type. Published aliases are accepted and normalized to their canonical MIME in the grant and artifact. |
size_bytes | integer | 是 | Exact local file byte length; the upload must match it. 限制：1–104857600 |
返回 AssetUploadOutput：grant_id、upload、media_type、mime_type、size_bytes、expires_at、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Create a short-lived upload grant for an image, audio, or video file. Follow the returned HTTP PUT instructions; its response returns the artifact_id.
Skill 安装
beatra.installations.register
登记当前连接所用的 Beatra Skill 包和版本。
| 积分 | 不扣积分 |
|---|---|
| 执行方式 | 直接返回结果 |
| 作用 | 向账号写入新数据 |
| 可重复调用 | 是 |
| 权限范围 | mcp:tools |
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
package_slug | string | 是 | 限制：长度 1–64 |
package_version | string | 是 | 限制：长度 5–64 |
platform | string | 是 | 限制：长度 1–64 |
external_installation_ref | string | 是 | 限制：长度 1–255 |
channel | any | 否 | — |
channel_locale | any | 否 | — |
route | any | 否 | — |
route_basis | any | 否 | — |
install_source | any | 否 | — |
install_source_basis | any | 否 | — |
environment | any | 否 | — |
返回 InstallationRegisterOutput：package_slug、package_version、recognized、first_seen_at、last_seen_at、error
错误码和对应的处理方法见错误与重试。
发给智能体的工具说明（英文原文）
Idempotently register the current Skill package for this authenticated installation, with optional channel, install source, network route and runtime environment. This telemetry call is non-billable.
最后更新