MCP tool reference

Every tool on the Beatra MCP server, generated from its tool definitions: what each tool does, its arguments, what it returns, and whether it consumes credits.

The Beatra MCP server at https://mcp.beatra.ai/mcp offers the tools below. This page is generated from the Beatra MCP server's tool list each time the docs are published. The live list is GET https://mcp.beatra.ai/tools, or tools/list on the MCP endpoint.

The installed Beatra Skill connects to this server and calls these tools for your agent, after one sign-in in the browser. Set it up with Install the Beatra Skill. Read this page to see what a call does before it runs; if a call fails, find its error code on Troubleshooting.

How to read each tool

Row	Meaning
Credits	Whether a successful call consumes Beatra credits. Generation prices come from `beatra.models.list`; social data prices from `beatra.social.tools.get`.
Runs as	An asynchronous task you poll with `beatra.tasks.get`, or a direct result.
Effect	Whether the call only reads, adds data to the account, or changes work in progress.
Repeat-safe	Whether an identical repeated call has the same effect. Task tools take a `client_request_id` for this.
Scopes	The permissions the sign-in must grant. A missing one returns `insufficient_scope`.

Images

`beatra.images.generate`

Generate one to four images from a text prompt.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `images:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	Yes	Required prompt containing at least one non-whitespace character. Limits: length ≥ 1
`count`	`integer`	No	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. Default: `1` Limits: 1–4
`canvas`	`ImagePresetCanvas \| ImageTargetCanvas`	No	Desired output canvas. Presets are quality tiers, and target dimensions may be normalized or vary; inspect output images for actual dimensions. Default: `{"type":"preset","tier":"2K","aspect":"16:9"}`
`seed`	`integer`	No	Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. Limits: 0–2147483647
`negative_prompt`	`string`	No	Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.
`enhance_prompt`	`boolean`	No	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`	No	Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. Limits: items 3–10
`output_relationship`	`ImageOutputRelationship`	No	Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. Default: `independent` Values: `independent`, `sequence`
`reasoning`	`boolean`	No	Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility.
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Create new images from one to four ordered reference images and a prompt.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `images:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	Yes	Required prompt containing at least one non-whitespace character. Limits: length ≥ 1
`count`	`integer`	No	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. Default: `1` Limits: 1–4
`canvas`	`ImageTransformPresetCanvas \| ImageTargetCanvas`	No	Desired output canvas. Preset `source` inherits the last input image's ratio; the omitted default is 2K at 16:9. Default: `{"type":"preset","tier":"2K","aspect":"16:9"}`
`seed`	`integer`	No	Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. Limits: 0–2147483647
`negative_prompt`	`string`	No	Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.
`enhance_prompt`	`boolean`	No	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`	No	Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. Limits: items 3–10
`images`	`array of ImageMediaInputUrl \| ImageMediaInputArtifact \| ImageMediaInputDataUri`	Yes	Ordered artifact, HTTPS URL, or data URI references. Limits: items 1–4
`output_relationship`	`ImageOutputRelationship`	No	Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. Default: `independent` Values: `independent`, `sequence`
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Edit a base image by instruction, optionally guided by more reference images and marked regions.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `images:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	Yes	Required prompt containing at least one non-whitespace character. Limits: length ≥ 1
`count`	`integer`	No	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. Default: `1` Limits: 1–4
`canvas`	`ImageEditPresetCanvas \| ImageTargetCanvas`	No	Desired output canvas. The default is a 2K tier derived from the first base image's ratio; actual output dimensions remain authoritative. Default: `{"type":"preset","tier":"2K","aspect":"source"}`
`seed`	`integer`	No	Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. Limits: 0–2147483647
`negative_prompt`	`string`	No	Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available.
`enhance_prompt`	`boolean`	No	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`	No	Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. Limits: items 3–10
`images`	`array of ImageMediaInputUrl \| ImageMediaInputArtifact \| ImageMediaInputDataUri`	Yes	Ordered inputs; images[0] is the base and later entries are references. Limits: items 1–4
`edit_regions`	`array of ImageEditRegion`	No	Flat normalized rectangles keyed by an input image_index. Runtime validation enforces cross-coordinate and collection relations. Limits: items 1–8
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Answer questions about one to eight images.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `images:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit or use 'auto' unless the user explicitly requests a concrete model. An explicit model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `auto`, `MiniMax-M3`
`prompt`	`string`	Yes	Required question or instruction containing non-whitespace characters. Limits: length 1–4000
`images`	`array of MediaInputUrl \| MediaInputArtifact \| ImageUnderstandingDataUri`	Yes	One through eight ordered image inputs. Each admitted image is billed once. Limits: items 1–8
`detail`	`string`	No	Visual detail preference. It does not change Beatra's per-image price. Default: `default` Values: `default`, `low`, `high`
`response_format`	`string`	No	Values: `text`, `json`
`temperature`	`number`	No	Limits: 0–2
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Video

`beatra.videos.enhance_prompt`

Rewrite a video prompt into a fuller one, optionally using image, video, or audio context. The result is the rewritten text.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`any`	No	Compatibility input only. Its value and type are ignored in the first release; Beatra resolves the available prompt-enhancement model internally. Default: `auto`
`prompt`	`string`	Yes	Required creative intent to expand into a production-ready video prompt. Limits: length 1–7000
`duration`	`integer`	Yes	Target video duration in integer seconds. Limits: 4–15
`aspect_ratio`	`string`	Yes	Target video aspect ratio. Text-only requests cannot use adaptive. Values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
`first_frame`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	Optional strict first-frame context image.
`last_frame`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	Optional strict last-frame context image.
`references`	`array of VideoReference`	No	Optional ordered image, video, or audio context. Reference mode and strict-frame mode are mutually exclusive. Limits: items ≤ 11
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Generate a video from a text prompt, with optional driving audio on models that support it.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer \| "auto"`	No	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`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`prompt`	`string`	Yes	Required description of the video to generate without source image or video media. Limits: length 1–20000
`audio`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	Optional driving audio for models that support audio-conditioned generation.
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Generate a video that starts from one image, optionally with driving audio.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer \| "auto"`	No	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`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`prompt`	`string`	No	Optional motion, scene, and camera instructions for animating the opening image. Limits: length ≤ 20000
`image`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	Yes	Required strict first-frame image; this is not a loose visual reference.
`driving_audio`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	Optional driving audio. Supplying it requires a model that supports this control.
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Generate a video from ordered image, video, and audio references.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer \| "auto"`	No	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`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`prompt`	`string`	No	Optional instructions describing how the ordered references should guide the output. Limits: length ≤ 20000
`references`	`array of VideoReference`	Yes	One to fifty ordered image, video, or audio references. Model-specific kind, count, duration, and combination limits still apply. Limits: items 1–50
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Generate a video that ends on a given last frame, optionally starting from a given first frame.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer \| "auto"`	No	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`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`prompt`	`string`	No	Optional instructions for the motion ending at the required last frame. Limits: length ≤ 20000
`first_frame`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	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`	Yes	Required image that must be the video's last frame.
`driving_audio`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	Optional driving audio. Supplying it requires a model that supports this control.
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Edit an existing video by instruction, with optional references.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer \| "auto"`	No	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`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`source_video`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	Yes	Required video whose existing content will be edited.
`instruction`	`string`	Yes	Required instruction describing changes to the source video. Limits: length 1–20000
`references`	`array of VideoReference`	No	Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. Limits: items ≤ 49
`audio_setting`	`string`	No	Optional edit-audio policy: auto lets a compatible model choose, while origin requests preservation of source audio. Values: `auto`, `origin`
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Add new footage before or after an existing clip.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. Default: `auto` Values: `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`	No	Content or qualities to avoid when supported by the selected model. Limits: length ≤ 500
`duration`	`integer`	Yes	Required final returned-video duration in integer seconds. It must exceed the trusted source-video duration; model-specific admission may narrow the range. Limits: 2–30
`aspect_ratio`	`string`	No	Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9`, `9:21`, `adaptive`
`resolution`	`string`	No	Requested model-defined output resolution tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. Values: `480p`, `720p`, `1080p`, `2k`, `4k`
`seed`	`integer`	No	Limits: 0–2147483647
`enhance_prompt`	`boolean`	No	Ask the selected model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written.
`watermark`	`boolean`	No	Whether generated video should include the model watermark.
`generate_audio`	`boolean`	No	Whether the selected model should generate synchronized audio.
`web_search`	`boolean`	No	Whether the selected model may use web search during generation.
`return_last_frame`	`boolean`	No	Whether to return the generated video's last frame as an image artifact.
`output_format`	`string`	No	Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. Values: `mp4`, `mov`
`video`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	Yes	The single source video to continue.
`direction`	`string`	Yes	Generate new content immediately before or after the source video's content. Values: `before`, `after`
`instruction`	`string`	Yes	Required instruction describing how the source video should continue. Limits: length 1–20000
`references`	`array of VideoReference`	No	Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. Limits: items ≤ 49
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Join your own clips into one MP4, with optional narration, background music, and burned-in subtitles.

Credits	Free
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`clips`	`array of ComposeClip`	Yes	Limits: items 1–12
`narration`	`MediaInputArtifact`	No	—
`music`	`ComposeMusic`	No	—
`subtitles`	`array of ComposeSubtitle`	No	Limits: items ≤ 200
`canvas`	`string`	No	Default: `9:16` Values: `9:16`, `16:9`, `1:1`, `3:4`
`model`	`string`	No	Default: `auto` Values: `auto`, `beatra-compose-v1`
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Answer questions about one video.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `videos:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit or use 'auto' unless the user explicitly requests MiniMax-M3. Default: `auto` Values: `auto`, `MiniMax-M3`
`prompt`	`string`	Yes	Required question or instruction containing non-whitespace characters. Limits: length 1–32000
`video`	`MediaInputUrl \| MediaInputArtifact \| VideoUnderstandingDataUri`	Yes	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`	No	Visual detail preference. It does not change Beatra's per-second price. Default: `default` Values: `default`, `low`, `high`
`response_format`	`string`	No	Values: `text`, `json`
`temperature`	`number`	No	Limits: 0–2
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Music

`beatra.music.generate`

Generate music from a prompt, with optional lyrics or reference audio.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `music:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model`	`string`	No	Omit unless the user requests a model. Default: `auto` Values: `auto`, `minimax-music-3.0`, `suno-6`, `suno-5.5`, `suno-v6`
`prompt`	`string`	Yes	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. Limits: length 1–2000
`lyrics`	`string`	No	Optional lyrics text. Must be omitted for instrumental music. Limits: length ≤ 5000
`instrumental`	`boolean`	No	When true, generate instrumental music without vocals. Default: `false`
`title`	`string`	No	Limits: length ≤ 100
`model_options`	`MusicModelOptions`	No	Options grouped by public music model family.
`reference_audio`	`MediaInputUrl \| MediaInputArtifact \| MediaInputDataUri`	No	—
`client_request_id`	`string`	Yes	Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Speech

`beatra.speech.prepare_script`

Turn text into a speech script directed for a voice and model (emotion, pauses, pronunciation) that beatra.speech.synthesize takes as it is. It can also recommend voices.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `speech:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`input`	`string`	Yes	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. Limits: length 1–50000
`instructions`	`string`	No	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. Limits: length ≤ 2000
`voice`	`string`	No	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`	No	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. Default: `auto` Values: `auto`, `minimax-speech-2.8-hd`, `minimax-speech-2.8-turbo`, `doubao-seed-tts-2.0`, `elevenlabs-v4-turbo`, `elevenlabs-v4`
`language`	`string`	No	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` Limits: length 2–32
`context`	`SpeechScriptContext`	No	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`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Synthesize speech from text with a Beatra voice.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `speech:generate`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model_options`	`object`	No	Per-model-family passthrough options; opaque to the platform, validated per model
`voice`	`string`	Yes	Opaque beatra voice_id (preset or cloned)
`input`	`string`	Yes	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). Limits: length 1–50000
`model`	`string`	No	Omit unless the user requests a model. Default: `auto` Values: `auto`, `minimax-speech-2.8-hd`, `minimax-speech-2.8-turbo`, `doubao-seed-tts-2.0`, `elevenlabs-v4-turbo`, `elevenlabs-v4`
`language`	`string`	No	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. Limits: length 2–32
`format`	`string`	No	Default: `mp3` Values: `mp3`, `wav`, `flac`, `opus`, `pcm`
`sample_rate`	`integer`	No	Values: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`
`speed`	`number`	No	Default: `1` Limits: 0.5–2
`volume`	`number`	No	Default: `1` Limits: ≤ 10, > 0
`pitch`	`number`	No	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: `0` Limits: -1–1
`emotion`	`string`	No	Provider-neutral discrete speaking emotion Values: `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `calm`, `fluent`
`subtitle_enable`	`boolean`	No	Request sentence-level subtitles with the audio. Subtitles are free; when present, output.subtitles carries the subtitle file URL and format. Default: `false`
`direction`	`string`	No	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`	No	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`	Yes	Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Check a speech request before submitting it: parse the markup, list warnings, and return the credit price.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`, `speech:generate`

Arguments

Name	Type	Required	Description
`voice`	`string`	Yes	Opaque beatra voice_id (preset or cloned)
`input`	`string`	Yes	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). Limits: length 1–50000
`model`	`string`	No	Model to check against (default auto) Default: `auto` Values: `auto`, `minimax-speech-2.8-hd`, `minimax-speech-2.8-turbo`, `doubao-seed-tts-2.0`, `elevenlabs-v4-turbo`, `elevenlabs-v4`
`language`	`string`	No	BCP-47 language hint Limits: length 2–32
`format`	`string`	No	Audio format the create call would use Default: `mp3` Values: `mp3`, `wav`, `flac`, `opus`, `pcm`
`sample_rate`	`integer`	No	Sample rate in Hz for the chosen format Values: `8000`, `16000`, `22050`, `24000`, `32000`, `44100`
`speed`	`number`	No	Speaking rate (0.5 to 2.0) Default: `1` Limits: 0.5–2
`volume`	`number`	No	Volume (0 to 10) Default: `1` Limits: ≤ 10, > 0
`pitch`	`number`	No	Normalized pitch (-1.0 to 1.0) Default: `0` Limits: -1–1
`emotion`	`string`	No	Emotion preset for the whole request Values: `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `calm`, `fluent`
`subtitle_enable`	`boolean`	No	Whether the create call would request subtitles Default: `false`
`direction`	`string`	No	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`	No	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`	No	Expert provider options, same as the create call

Returns McpSpeechValidateOutput: valid, warnings, weighted_characters, price_credits, execution, script_markup, limitations, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Voices

`beatra.voices.clone`

Clone a voice from a clean single-speaker sample, once the user confirms they have the rights to that voice.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `voices:write`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`model_options`	`object`	No	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`	Yes	Clean single-speaker voice sample (uploaded artifact or HTTPS URL), ~10s-5min
`prompt`	`VoiceClonePrompt`	No	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`	Yes	Limits: length 1–255
`model`	`string`	No	Clone engine. Omit unless the user explicitly asks for a specific clone engine; 'auto' (the default) lets the platform choose. Default: `auto` Values: `auto`, `minimax-voice-clone`, `doubao-voice-clone-2.0`, `elevenlabs-voice-clone`
`language`	`string`	No	Optional BCP-47 language hint for the cloned voice Limits: length 2–32
`consent_attested`	`true`	Yes	Caller asserts it has the rights to clone this voice. Recorded, not verified.
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Activate a cloned voice whose clone result asks for activation, once the user agrees to the quoted price.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `voices:write`, `wallet:spend`, `tasks:read`

Arguments

Name	Type	Required	Description
`voice_id`	`string`	Yes	The voice_id from the clone result. Limits: length 1–64
`confirmation_token`	`string`	No	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. Limits: length 1–1024
`confirm_credits`	`integer`	No	The quoted price_credits, repeated to confirm the user agreed to exactly that price. Limits: ≥ 0
`client_request_id`	`string`	Yes	Stable retry identity for this billable operation. Reuse only for the exact same generation arguments. Limits: length 1–128

Returns VoiceActivateOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error, voice, charged_credits, quote

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

List the preset and cloned voices available for speech.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`, `voices:read`

Arguments

Name	Type	Required	Description
`language`	`string`	No	Limits: length ≤ 32
`gender`	`string`	No	Values: `male`, `female`, `neutral`
`category`	`string`	No	Values: `preset`, `cloned`
`query`	`string`	No	Limits: length ≤ 128
`model`	`string`	No	Compatible model id
`age_group`	`string`	No	child, youth, adult, or senior
`voice_id`	`string`	No	Exact voice_id Limits: length ≤ 64
`limit`	`integer`	No	Page size Default: `50` Limits: 1–500
`cursor`	`string`	No	voice_id of the last voice on the previous page Limits: length ≤ 64
`use_case`	`string`	No	Voices tagged with this use case
`search`	`string`	No	Case-insensitive text found in the display name or the persona Limits: length ≤ 64
`status`	`string`	No	Which voices to list: ready (default, usable for speech), pending_activation (cloned previews that need activation), expired, or any. Default: `ready` Values: `ready`, `pending_activation`, `expired`, `any`

Returns VoiceListOutput: voices, default_voice_id, error, next_cursor, total_count

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Rename a cloned voice, or make a voice the account's default.

Credits	Free
Runs as	Direct result
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `voices:write`

Arguments

Name	Type	Required	Description
`voice_id`	`string`	Yes	Limits: length 1–64
`display_name`	`string`	No	New name for one of this account's cloned voices. Limits: length 1–40
`make_default`	`boolean`	No	true makes this voice the account's default; false or omitted leaves the default as it is. Clearing the default is console-only.

Returns VoiceUpdateOutput: voice_id, display_name, is_default, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Avatars

`beatra.avatars.list`

List the portraits saved as avatars for presenter videos, each with its paired voice.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`, `artifacts:read`

Arguments

This tool takes no arguments.

Returns AvatarListOutput: avatars, default_avatar_id, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

Save an image in the account as a named avatar for later presenter videos, once the user confirms the portrait consent.

Credits	Free
Runs as	Direct result
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `artifacts:write`

Arguments

Name	Type	Required	Description
`artifact_id`	`string`	Yes	An image artifact_id in this account, from beatra.assets.upload or an earlier task. Limits: length 1–64
`display_name`	`string`	Yes	The name the user gave this avatar. Limits: length 1–40
`purpose`	`string`	No	Optional use, such as 'course lecturer'. Limits: length ≤ 60
`voice_id`	`string`	No	Optional voice to pair with this avatar. Limits: length 1–64
`make_default`	`boolean`	No	Also make this the account's default avatar. Default: `false`
`consent_attested`	`true`	Yes	Set true only after the user confirmed the portrait consent sentence.
`consent_subject`	`string`	Yes	self: the user is the person pictured. authorized_other: the user has that person's separate consent. Values: `self`, `authorized_other`

Returns AvatarSaveOutput: avatar, default_avatar_id, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Search the public social data tools by platform, keyword, or capability family.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

Name	Type	Required	Description
`query`	`string`	No	Limits: length ≤ 256
`platform`	`string`	No	Values: `tiktok`, `douyin`, `xiaohongshu`, `instagram`, `youtube`, `twitter`
`capability_family`	`string`	No	Values: `content`, `creator`, `comments`, `trends`, `captions`
`limit`	`integer`	No	Default: `10` Limits: 1–20
`cursor`	`string`	No	Limits: length ≤ 256

Returns SocialToolsSearchOutput: items, next_cursor, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

Search public social data tools by platform, keyword, or capability_family. This call is not billable.

Read one public social data tool: its arguments, schema_hash, and credit price.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

Name	Type	Required	Description
`operation_key`	`string`	Yes	Limits: length 1–128

Returns SocialToolsGetOutput: operation, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

Read one public social data tool, including its arguments, schema_hash, and credit price. This call is not billable.

Run one public social data lookup as a task.

Credits	Consumes credits
Runs as	Asynchronous task: poll `beatra.tasks.get` until it ends
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`, `wallet:spend`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`operation_key`	`string`	Yes	Limits: length 1–128
`schema_hash`	`string`	Yes	—
`arguments`	`object`	No	—
`client_request_id`	`string`	Yes	Submit exactly once, then poll with beatra.tasks.get. Limits: length 1–128

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Models

`beatra.models.list`

List the models selectable for one capability, with their live controls, limits, and credit prices.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

Name	Type	Required	Description
`capability`	`string`	Yes	Generation capability such as text_to_image.
`include_activation_required`	`boolean`	No	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. Default: `false`

Returns ModelListOutput: account_offer, top_up, capability, default_model, auto, models, max_output_images, max_canvas_pixels, starting_credits, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

List models currently selectable for one Beatra generation capability, including live supported controls, constraints, customer credit prices, and billing basis. capability is 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.

Tasks

`beatra.tasks.list`

List recent tasks created by this connection.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`, `tasks:read`

Arguments

Name	Type	Required	Description
`cursor`	`string`	No	—
`limit`	`integer`	No	Default: `10` Limits: 1–50
`status`	`string`	No	Values: `queued`, `running`, `succeeded`, `failed`, `canceled`
`capability`	`string`	No	—

Returns TaskListOutput: items, next_cursor, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

List recent Beatra tasks created by this MCP connection.

`beatra.tasks.get`

Read one task created by this connection: its status, results, and charge.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`, `tasks:read`, `artifacts:read`

Arguments

Name	Type	Required	Description
`task_id`	`string`	Yes	Limits: length ≥ 1

Returns TaskToolOutput: task_id, status, terminal, resolved_model, usage, billing, task, artifacts, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

Read a Beatra task created by this MCP connection.

`beatra.tasks.cancel`

Cancel a task created by this connection.

Credits	Free
Runs as	Direct result
Effect	Changes work in progress
Repeat-safe	Yes
Scopes	`mcp:tools`, `tasks:cancel`

Arguments

Name	Type	Required	Description
`task_id`	`string`	Yes	Limits: length ≥ 1

Returns TaskCancelOutput: task_id, status, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Credits

`beatra.wallet.get`

Read the account's credit balance and the next batch of credits to expire.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

This tool takes no arguments.

Returns WalletGetOutput: balance_credits, expiring_credits, non_expiring_credits, next_expiry_at, next_expiry_credits, topup_url, concurrent_task_limit, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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`

List the account's credit history, newest first: charges, refunds, top-ups, and expiry.

Credits	Free
Runs as	Direct result
Effect	Read-only
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

Name	Type	Required	Description
`cursor`	`string`	No	—
`limit`	`integer`	No	Default: `20` Limits: 1–50

Returns WalletLedgerOutput: items, next_cursor, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

Uploads

`beatra.assets.upload`

Get a short-lived upload URL for a local image, audio, or video file. The upload's response returns the artifact ID that other tools take as input.

Credits	Free
Runs as	Direct result
Effect	Adds data to the account
Repeat-safe	No: each call has its own effect
Scopes	`mcp:tools`, `artifacts:write`

Arguments

Name	Type	Required	Description
`filename`	`string`	No	Limits: length 1–255
`mime_type`	`string`	Yes	Exact media MIME type. Published aliases are accepted and normalized to their canonical MIME in the grant and artifact.
`size_bytes`	`integer`	Yes	Exact local file byte length; the upload must match it. Limits: 1–104857600

Returns AssetUploadOutput: grant_id, upload, media_type, mime_type, size_bytes, expires_at, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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 installation

`beatra.installations.register`

Credits	Free
Runs as	Direct result
Effect	Adds data to the account
Repeat-safe	Yes
Scopes	`mcp:tools`

Arguments

Name	Type	Required	Description
`package_slug`	`string`	Yes	Limits: length 1–64
`package_version`	`string`	Yes	Limits: length 5–64
`platform`	`string`	Yes	Limits: length 1–64
`external_installation_ref`	`string`	Yes	Limits: length 1–255
`channel`	`any`	No	—
`channel_locale`	`any`	No	—
`route`	`any`	No	—
`route_basis`	`any`	No	—
`install_source`	`any`	No	—
`install_source_basis`	`any`	No	—
`environment`	`any`	No	—

Returns InstallationRegisterOutput: package_slug, package_version, recognized, first_seen_at, last_seen_at, error

Error codes and what to do about each one: Errors & retries.

Tool description sent to the agent

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.

On this page