# Beatra Agent Markdown guides > Every self-contained capability guide from https://docs.beatra.ai/llms/, in one file. Generated from the English capability pages; the live model catalog and public OpenAPI stay authoritative. - https://docs.beatra.ai/llms/images-understanding.md - https://docs.beatra.ai/llms/images-text-to-image.md - https://docs.beatra.ai/llms/images-image-to-image.md - https://docs.beatra.ai/llms/images-edit.md - https://docs.beatra.ai/llms/videos-text-to-video.md - https://docs.beatra.ai/llms/videos-image-to-video.md - https://docs.beatra.ai/llms/videos-reference-to-video.md - https://docs.beatra.ai/llms/videos-frames-to-video.md - https://docs.beatra.ai/llms/videos-video-edit.md - https://docs.beatra.ai/llms/videos-video-extend.md - https://docs.beatra.ai/llms/videos-video-prompt-enhancement.md - https://docs.beatra.ai/llms/videos-understanding.md - https://docs.beatra.ai/llms/audio-text-to-speech.md - https://docs.beatra.ai/llms/voices-clone.md - https://docs.beatra.ai/llms/voices-management.md - https://docs.beatra.ai/llms/music-text-to-music.md - https://docs.beatra.ai/llms/music-reference-audio-to-music.md - https://docs.beatra.ai/llms/social.md --- # Beatra MCP — Understand images > Analyze one to eight images with stable input limits and per-image pricing. > Self-contained workflow guide for MCP clients and AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/image-understanding - Primary agent surface: authenticated MCP at `https://mcp.beatra.ai/mcp`. - Billable action: `beatra.images.understand`. - Dynamic model facts: call `beatra.models.list` with `capability: "image_to_text"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. - Alternative application surface: REST/OpenAPI with a stable `Idempotency-Key`. This direct MCP capability does not depend on an installable Skill package. --- Image understanding is available through authenticated MCP and REST as a preview: the capability and price may change. Submit one to eight ordered images and a prompt; Beatra returns a durable asynchronous task. ## MCP Call `beatra.images.understand` with one stable `client_request_id`: ```json { "client_request_id": "understand-products-01", "model": "auto", "prompt": "Compare the products and list the important differences.", "images": [ { "type": "url", "url": "https://example.com/front.jpg" }, { "type": "artifact", "artifact_id": "artifact_back" } ], "detail": "default", "response_format": "text" } ``` Use `beatra.models.list` with `capability: "image_to_text"` when current model, limit, or price facts matter. Submit the finalized arguments once, then poll the returned `task_id` with `beatra.tasks.get`. On success, the answer is in both `structuredContent.task.output.text` and the MCP text content. For a local image, call `beatra.assets.upload` with the exact MIME type and byte length, perform the returned HTTPS `PUT` with the raw bytes, and pass the returned `artifact_id` as an `artifact` input. The uploaded source remains in the account asset library. ## REST Send the same understanding fields, without `client_request_id`, to `POST /v1/images/responses` and provide a stable `Idempotency-Key` header. Poll `GET /v1/tasks/{task_id}` until terminal. Each input may be a in your account `artifact`, an external HTTPS `url`, or a base64 `data_uri`. External and inline inputs are validated, stored in the account's uploaded-material library, and passed to the model from Beatra's CDN. ## Contract - `prompt` is required and must contain non-whitespace text. - `images` is required and accepts 1–8 ordered images. - Each decoded image is limited to 10 MiB. - `detail` accepts `default`, `low`, or `high` and defaults to `default`. It does not change the price. - `thinking` is not a public field. MiniMax M3 uses adaptive thinking internally. - The selectable model is `MiniMax-M3`; use `auto` unless a specific model is required. Live availability remains authoritative. ## Billing Successful requests cost **5 credits per accepted image**. A request with eight images therefore costs 40 credits. Provider token usage remains internal and does not change this endpoint's customer charge. Failed tasks are not charged. Uploaded source materials remain available in the account asset library; temporary server files used during ingestion are deleted after processing. --- ## Appendix: shared direct MCP contract ### Retry identity One logical understanding request has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. The task is authoritative for the resolved model, answer, usage quantity, and charged credits. Successful image understanding is billed by the number of images accepted; successful video understanding is billed by input-video seconds rounded up. Failed tasks are not charged. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Generate images from text > Create one or more images without a source image. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/text-to-image - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.images.generate` - Dynamic model facts: call `beatra.models.list` with `capability: "text_to_image"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Create one or more images without a source image. ## Primary agent path Use the Universal Skill with `beatra.images.generate` when there is no source image. It creates a billable asynchronous task. 1. Finalize the subject, composition, style, canvas, and output count. 2. Use `model: "auto"` or omit `model` for ordinary requests. Call `beatra.models.list` with `capability: "text_to_image"` before a model, control, compatibility, or price comparison. 3. Create one opaque `client_request_id`, submit once, and save the returned `task_id`. 4. Poll that task with `beatra.tasks.get` until terminal. ## Tool arguments ```json { "prompt": "A quiet flower shop with carved wooden doors at blue hour", "count": 1, "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" }, "output_relationship": "independent", "client_request_id": "img-generate-opaque-1" } ``` Use a target canvas such as `{ "type": "target", "width": 1536, "height": 1024 }` when exact requested dimensions matter. Actual stored image dimensions remain authoritative. ## Limits, defaults, and controls - Request one to four outputs; `count` defaults to 1. - Generate and transform default to a 2K 16:9 canvas. Edit defaults to a 2K canvas whose aspect ratio follows its base image. - `output_relationship` defaults to `independent`; use `sequence` only when the selected interface card allows a coherent set. - An omitted `seed` is random. - Null or omitted `enhance_prompt` and `reasoning` use the selected model's documented default. - Exact canvas, negative prompt, palette, prompt enhancement, reasoning, and seed availability is model- and intent-specific. Follow `beatra.models.list`; unsupported controls fail instead of being ignored. The current stable image aliases also include `qwen-image-3.0-pro` and `qwen-image-3.0`, alongside `wan2.7-image-pro`, `wan2.7-image`, `qwen-image-2.0-pro`, `qwen-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `gpt-image-2`. GPT Image 2.5 Flare and Sunburst are public for explicit selection and sit in text-to-image `auto` immediately before GPT Image 2 (after Qwen 2.0 / Qwen 3). Requests Qwen cannot handle but GPT can, including long prompts at 2K and 4K, select Flare. An explicit GPT Image 2 or 2.5 request requires `count: 1`, an `independent` output, and a preset `1K`, `2K`, or `4K` canvas. They do not accept a target canvas, seed, negative prompt, prompt enhancement, reasoning, or palette. GPT Image 2.5 accepts a 20,000-character prompt. Published per-successful-image prices are 90/150/230 credits for GPT Image 2 and 180/300/460 credits for both 2.5 models. A 4K `1:1` request can be accepted. Read `pricing.options` from `beatra.models.list` and select the option matching the actual output resolution; do not copy models or prices into an agent prompt. Wan sequence capacity above four is not exposed: every public output collection stops at four. ## Billing, task status, and recovery The request reserves the requested count, but it is charged only for successfully persisted images. A partial result therefore settles to its actual artifact count. Text-to-image has no supplier input-image component. Use terminal task `usage` and `billing` fields as final truth. `queued` and `running` are not failures. If the create response is lost, retry the identical arguments with the same `client_request_id`; never create a replacement task merely because work is still running. Any changed argument requires a new ID. ## REST API Custom integrations may call `POST /v1/images/generations` and then use the shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_generations_v1_images_generations_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Transform images with references > Use ordered images to guide a new composition. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/image-to-image - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.images.transform` - Dynamic model facts: call `beatra.models.list` with `capability: "image_to_image"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Use ordered images to guide a new composition. ## Primary agent path Use `beatra.images.transform` when references guide identity, style, layout, or content but the whole composition may change. 1. Upload local inputs with `beatra.assets.upload` and reuse their artifact IDs. 2. Keep one to four ordered input images. A source-shaped preset follows the last image. 3. Use `model: "auto"` unless the user requests a model. Call `beatra.models.list` with `capability: "image_to_image"` before choosing a model, control, canvas, or price. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "prompt": "Keep the character recognizable and place them in a winter market", "images": [ { "type": "artifact", "artifact_id": "artifact_character" }, { "type": "artifact", "artifact_id": "artifact_style" } ], "count": 1, "canvas": { "type": "preset", "tier": "2K", "aspect": "16:9" }, "output_relationship": "independent", "client_request_id": "img-transform-opaque-1" } ``` HTTPS URLs, artifact IDs, and small inline data URIs are accepted according to the selected interface card. Artifact IDs are preferred for uploaded local files and repeat use. ## Limits, defaults, and model compatibility - Transform accepts one to four ordered input images and requests one to four outputs. Its default is one output on a 2K 16:9 canvas. - `aspect: "source"` follows the last input. A target canvas requests explicit width and height; inspect the final artifact for actual dimensions. - `output_relationship` defaults to `independent`; compatible models may create a coherent `sequence`. - Negative prompt, prompt enhancement, palette, seed, and sequence support come from `beatra.models.list`. Explicit Qwen Image 2.0 and 3.0 requests accept at most three inputs. Auto keeps the public maximum of four by selecting an eligible model for the complete request. No input is dropped, merged, or reordered. The stable aliases are `qwen-image-3.0-pro`, `qwen-image-3.0`, `wan2.7-image-pro`, `wan2.7-image`, `qwen-image-2.0-pro`, `qwen-image-2.0`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `gpt-image-2`. Qwen Image 3 is in image-to-image `auto`. GPT Image 2.5 Flare and Sunburst sit in image-to-image `auto` immediately before GPT Image 2, still behind Qwen and Wan. They accept up to four ordered references and exactly one independent output on a preset `1K`, `2K`, or `4K` canvas, with a 20,000-character prompt. They do not accept a target canvas, seed, negative prompt, prompt enhancement, reasoning, or palette. Published per-successful-image prices are 90/150/230 credits for GPT Image 2 and 180/300/460 credits for both 2.5 models. A 4K `1:1` request can be accepted. 4K transform `auto` selects Flare. Discovery (`beatra.models.list`) is the current source of `pricing.options`; select the option matching the actual output resolution. Tasks are charged only for successfully persisted images. Input references do not add extra credits for each reference image; the hidden supplier input cost is covered by Beatra. Do not copy models or prices into an agent prompt. ## Task status and recovery Keep polling the same `task_id` while it is queued or running. Recover a lost create response by sending identical arguments with the same `client_request_id`. A changed reference, order, prompt, model, or control is a new logical request and needs a new ID. ## REST API Custom integrations use `POST /v1/images/image-to-image`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_i2i_v1_images_image_to_image_post) for the complete schema. Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Edit a base image > Preserve a base image while applying an instruction or bounded change. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/images/image-edit - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.images.edit` - Dynamic model facts: call `beatra.models.list` with `capability: "image_edit"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Preserve a base image while applying an instruction or bounded change. ## Primary agent path Use `beatra.images.edit` when the first image must remain the base canvas. Later ordered images may guide the edit. 1. Upload local inputs with `beatra.assets.upload` and use the returned artifact IDs. 2. Put the base first, followed by up to three optional references. 3. Call `beatra.models.list` with `capability: "image_edit"` when model, region, control, canvas, or price compatibility matters. Otherwise use `model: "auto"`. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "prompt": "Replace the sign inside the selected area and preserve everything else", "images": [ { "type": "artifact", "artifact_id": "artifact_base" } ], "edit_regions": [ { "image_index": 0, "x": 0.58, "y": 0.20, "width": 0.30, "height": 0.18 } ], "count": 1, "canvas": { "type": "preset", "tier": "2K", "aspect": "source" }, "client_request_id": "img-edit-opaque-1" } ``` Each normalized region must remain inside its image. Each input can have at most two regions. Omit `edit_regions` for a whole-image instruction. ## Limits, defaults, and model compatibility - Edit accepts one to four ordered input images and requests one to four outputs. The first image is the base. - Edit defaults to a 2K canvas whose ratio follows the first image; `count` defaults to 1. - Exact canvas, negative prompt, prompt enhancement, palette, region, and seed support is described by `beatra.models.list`. - Explicit Qwen Image 2.0 and 3.0 requests accept at most three inputs. `auto` keeps the public maximum of four by selecting an eligible model. Incompatible explicit requests fail before charge and never discard an input. The stable aliases are `qwen-image-3.0-pro`, `qwen-image-3.0`, `wan2.7-image-pro`, `wan2.7-image`, `qwen-image-2.0-pro`, and `qwen-image-2.0`. Qwen Image 3 is initially named-only and does not change `auto`. Read `pricing.options` from live discovery and select the option matching the actual output resolution. Billing settles to the number of successfully persisted images, including partial output; input references do not add extra credits for each reference image. Do not copy models or prices into an agent prompt. ## Task status and recovery Poll the same `task_id` until terminal. Retry a lost create response only with identical arguments and the same `client_request_id`. Any new instruction, input order, region, model, or output setting is new work and needs a new ID. ## REST API Custom integrations use `POST /v1/images/edits`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/images/images_edits_v1_images_edits_post) for the complete contract. Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Generate video from text > Create video clips from a scene description, with optional audio guidance. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/text-to-video - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.generate` - Dynamic model facts: call `beatra.models.list` with `capability: "text_to_video"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Create video clips from a scene description, with optional audio guidance. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.videos.generate`. The tool is billable and returns an asynchronous task. 1. Finalize the scene, motion, duration, and fidelity choices. 2. If a model, audio support, constraint, or price matters, call `beatra.models.list` with `capability: "text_to_video"`. Otherwise use `model: "auto"` or omit `model`. 3. Upload local audio with `beatra.assets.upload` and use its artifact ID. 4. Create one opaque `client_request_id` and submit the final arguments once. 5. Poll the returned task with `beatra.tasks.get` until it is terminal. ## Tool arguments ```json { "prompt": "A slow dolly toward a ceramic cup in warm window light", "audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" }, "resolution": "720p", "duration": 6, "client_request_id": "vid-text-opaque-1" } ``` `audio` is optional and must be supported by the selected model. Omit it for a visually driven result. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. `beatra.models.list` is the current source for selectable models, supported audio, resolutions, durations, aspect ratios, defaults, and prices. Do not copy a model catalog or price table into an agent prompt. Resolution and duration normally affect cost. Omit them when the user has no preference so request-dependent `auto` selection can apply the selected model's declared defaults. Set them only from user intent or current discovery. An explicit model is never silently replaced. ### Seedance 2.5 Set `model: "seedance-2.5"` or `"seedance-2.5-fast"` for **Seedance 2.5** (`Seedance 2.5` / `Seedance 2.5 Fast`), or `"seedance-2.0"` / `"seedance-2.0-fast"` for the 2.0 tier. Seedance 2.5 supports multi-aspect cinematic motion and synchronized audio options; check `beatra.models.list` with `capability: "text_to_video"` for live per-second credit rates and supported resolution/duration combinations. ### MiniMax H3 Set `model: "minimax-h3"` for MiniMax H3. It requires a prompt and accepts integer durations from 4 through 15 seconds. Public `720p` costs 370 credits per output second; `2k` costs 590 credits per output second. Omitting resolution with explicit H3 now defaults to 720p. Its supported controls are `prompt`, `resolution`, `duration`, `aspect_ratio`, and `watermark`; input audio is not accepted in this mode. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime` for 2–30 second clips at `480p`, `720p`, or `1080p` (default `720p`). Optional `audio` is driving audio and is not billed. `480p` is 225 credits per output second on `wan3.0-video` and 335 on the higher tier. `negative_prompt` is not supported. Confirm prices with `beatra.models.list`. ## Task status and recovery `queued` and `running` are not failures. Keep polling the same `task_id`; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same `client_request_id`. If any input changes, use a new ID. Return artifacts, resolved model, and charged or refunded credits only from the terminal task response. ## REST API Direct protocol integrations may use `POST /v1/videos/text-to-video` and the shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_t2v_v1_videos_text_to_video_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Animate an image > Turn one still image into motion, optionally following driving audio. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/image-to-video - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.animate` - Dynamic model facts: call `beatra.models.list` with `capability: "image_to_video"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Turn one still image into motion, optionally following driving audio. ## Primary agent path Use `beatra.videos.animate` when one image defines the opening composition. If both a first and last frame matter, use `beatra.videos.interpolate` instead. 1. Upload a local image and optional local audio with `beatra.assets.upload`. 2. Call `beatra.models.list` with `capability: "image_to_video"` when model constraints, audio support, or price matter. 3. Describe motion and camera behavior without contradicting the source image. 4. Submit once with one `client_request_id`, then poll with `beatra.tasks.get`. ## Tool arguments ```json { "prompt": "The subject turns toward camera while the camera eases forward", "image": { "type": "artifact", "artifact_id": "artifact_first_frame" }, "driving_audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" }, "resolution": "720p", "duration": 6, "client_request_id": "vid-animate-opaque-1" } ``` `driving_audio` is optional. The image can also be a public HTTPS `url` media reference or a `data_uri` whose complete encoded value is at most 256KB; use an uploaded artifact for anything larger. Local filesystem paths are never valid input. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. Use `beatra.models.list` as the current source for accepted media combinations, audio limits, resolutions, duration, derived aspect-ratio behavior, defaults, and prices. Image-driven models may derive the output ratio from the input and ignore `aspect_ratio`. Resolution and duration normally affect cost. Do not silently reduce either. Use `model: "auto"` unless the user names a selectable model. ### MiniMax H3 Set `model: "minimax-h3"` to animate an image with MiniMax H3. The prompt is required, duration is 4–15 seconds, and the output ratio is derived from the input image. Public `720p` costs 370 credits per output second; `2k` costs 590. Omitting resolution with explicit H3 now defaults to 720p. H3 accepts `watermark` but not driving audio or the other optional controls. The input image is free. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime`. Duration is 2–30 seconds; aspect ratio follows the image. Do not send `driving_audio` (it cannot mix with the first frame). `480p` is 225 credits per output second on `wan3.0-video` and 335 on the higher tier. ## Saved avatars A presenter portrait can be saved as an avatar on the account and reused in any later session. - `beatra.avatars.list` is read-only and non-billable. It returns the avatars (default first) and `default_avatar_id`; each avatar carries `image.artifact_id` and its paired `voice`. Pass `image.artifact_id` as the portrait to `beatra.videos.animate`, after checking the image against the live model card as usual. - `beatra.avatars.save` is non-billable. Call it only after the user agreed to save the portrait and confirmed the consent sentence: `consent_subject` is `self` (the user is pictured) or `authorized_other` (the user has that person's separate consent). Saving the same image again returns the same avatar. ```json { "artifact_id": "artifact_01JX...", "display_name": "Dr. Peng, lectures", "purpose": "course lecturer", "voice_id": "voice_01JX...", "consent_attested": true, "consent_subject": "self" } ``` ## Task status and recovery Poll the same `task_id` through `queued` and `running`. If the create response is lost, retry identical arguments with the same `client_request_id`; changed image, audio, prompt, model, or output controls require a new ID. Terminal task state is the only source for artifacts and billing. ## REST API Direct protocol integrations may use `POST /v1/videos/image-to-video`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_i2v_v1_videos_image_to_video_post). Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Generate from references > Preserve subjects, products, scenes, video identity, or voice across a new video. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/reference-to-video - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.generate_from_references` - Dynamic model facts: call `beatra.models.list` with `capability: "reference_to_video"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Preserve subjects, products, scenes, video identity, or voice across a new video. ## Primary agent path Use `beatra.videos.generate_from_references` when media should guide identity, appearance, style, product, background, pose, or voice. Use edit when the goal is to change an existing clip rather than create a new one. 1. Upload every local image, video, and voice reference. 2. Give each reference `kind: "image"`, `kind: "video"`, or `kind: "audio"`, preserve its order, and use the model's returned prompt-reference syntax. 3. Call `beatra.models.list` with `capability: "reference_to_video"` for current counts, media combinations, duration rules, and prices. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "prompt": "Video 1 presents Image 1 in a bright studio scene while keeping the same voice", "references": [ { "kind": "image", "media": { "type": "artifact", "artifact_id": "artifact_product" } }, { "kind": "video", "media": { "type": "artifact", "artifact_id": "artifact_presenter" }, "reference_voice": { "type": "artifact", "artifact_id": "artifact_voice" } } ], "resolution": "720p", "duration": 6, "client_request_id": "vid-refs-opaque-1" } ``` `reference_voice` is an audio media reference attached to one reference item; it is not a Boolean. For `auto`/Wan, images and videos are numbered separately as `Image n` and `Video n` (or `图n` and `视频n`). HappyHorse image references use `[Image n]` in array order. HappyHorse/Wan reject semantic `role`; only use it when model discovery explicitly lists supported roles for another selected model. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. `beatra.models.list` is authoritative for reference counts, supported kinds, prompt-reference syntax, optional voice support, conditional duration limits, aspect-ratio behavior, and prices. Input-video seconds can affect billing when the returned price metadata says so. ### MiniMax H3 Set `model: "minimax-h3"` for multimodal reference generation lasting 4–15 seconds. H3 requires a prompt and accepts up to five images, three videos, and three audio files. Referenced video and audio are each limited to 15 seconds in aggregate; audio-only references are valid. Do not send `role` or `reference_voice`. Input images and audio are free. At public `720p`, accepted input-video and generated output time each cost 370 credits per second; at `2k`, each costs 590. Omitting resolution with explicit H3 now defaults to 720p. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime`. Up to 10 images, 5 videos, and 5 audio files (20 total); reference video/audio each cap at 15 seconds. Audio requires a companion image or video. Input-video seconds are billed at the same per-second rate as output. `480p` is 225 credits/s on `wan3.0-video` and 335 on the higher tier. ## Task status and recovery Keep reference order stable across an identical retry. Poll the same task while it is `queued` or `running`. Any changed reference, voice, prompt, or output control is a new logical request and needs a new `client_request_id`. ## REST API Direct protocol integrations may use `POST /v1/videos/reference-to-video`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_r2v_v1_videos_reference_to_video_post). Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Generate toward a final frame > Generate motion toward a controlled last frame, with an optional first frame. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/frames-to-video - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.interpolate` - Dynamic model facts: call `beatra.models.list` with `capability: "frames_to_video"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Generate motion toward a controlled last frame, with an optional first frame. ## Primary agent path Use `beatra.videos.interpolate` when a required last image defines the ending. Add `first_frame` only when the opening must also be controlled. 1. Upload the last frame, an optional first frame, and optional driving audio. 2. Call `beatra.models.list` with `capability: "frames_to_video"` for current media combinations, duration, resolution, audio support, and prices. 3. Describe the movement toward the ending, including the transition from the first frame when one is supplied. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "prompt": "The product rises and rotates smoothly between the two views", "first_frame": { "type": "artifact", "artifact_id": "artifact_start" }, "last_frame": { "type": "artifact", "artifact_id": "artifact_end" }, "driving_audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" }, "resolution": "720p", "duration": 6, "client_request_id": "vid-frames-opaque-1" } ``` `last_frame` is required; `first_frame` and `driving_audio` are optional but must be supported by the selected model. Image-driven aspect-ratio rules come from model discovery. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. Use `beatra.models.list` instead of a static model table. It returns selectable models, accepted frame/audio combinations, constraints, defaults, ignored fields, and prices. Resolution and duration normally affect cost; do not silently change them. ### MiniMax H3 Set `model: "minimax-h3"` for a last-frame-only or first-and-last-frame H3 request. The last frame and prompt are required; the first frame is optional. Duration is 4–15 seconds. Public `720p` costs 370 credits per output second; `2k` costs 590. Omitting resolution with explicit H3 now defaults to 720p. H3 accepts `watermark` but not driving audio or the other optional controls. Supplied boundary images are free. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime` with first and last frames. Duration is 2–30 seconds. Do not send `driving_audio`. `480p` is 225 credits per output second on `wan3.0-video` and 335 on the higher tier. ## Task status and recovery Poll the same task through `queued` and `running`. A lost create response may be retried only with identical arguments and the same `client_request_id`. Swapping either frame or changing audio, prompt, or output settings requires a new ID. ## REST API Direct protocol integrations may use `POST /v1/videos/frames-to-video`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_f2v_v1_videos_frames_to_video_post). Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Edit an existing video > Apply an instruction or reference-guided change to an existing clip. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/video-edit - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.edit` - Dynamic model facts: call `beatra.models.list` with `capability: "video_edit"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Apply an instruction or reference-guided change to an existing clip. ## Primary agent path Use `beatra.videos.edit` when the existing clip remains the source timeline. If the goal is to continue beyond its endpoint, use `beatra.videos.extend`. 1. Upload the local source video and any local reference images. 2. Call `beatra.models.list` with `capability: "video_edit"` for current input limits, duration semantics, audio behavior, controls, and prices. 3. State what must change and what must remain stable. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "instruction": "Replace the cup with the referenced blue bottle and keep the camera move", "source_video": { "type": "artifact", "artifact_id": "artifact_source_video" }, "references": [ { "kind": "image", "media": { "type": "artifact", "artifact_id": "artifact_blue_bottle" } } ], "audio_setting": "origin", "resolution": "720p", "client_request_id": "vid-edit-opaque-1" } ``` `audio_setting` is `auto` or `origin` when supported. An explicit `duration` can mean truncating the source from time zero; omit it when the desired behavior is to preserve the full eligible input. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. Use `beatra.models.list` as the current source for selectable models, source duration and reference-image limits, output duration rules, resolution, aspect ratio, audio behavior, and price inputs. Editing may bill input-video and output seconds; use the returned billing unit rather than estimating from memory. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime`. Duration follows the source (omit `duration`; source at most 15 seconds). Up to 10 reference images; no reference video or audio. Source and output seconds both bill. `480p` is 225 credits/s on `wan3.0-video` and 335 on the higher tier. ## Task status and recovery Poll the same `task_id` until terminal. A lost response can be recovered with identical arguments and the same `client_request_id`. Any new instruction, source, reference, audio choice, or output setting is a new request. ## REST API Direct protocol integrations use `POST /v1/videos/edit`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_edit_v1_videos_edit_post) for the complete request contract. Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Extend an existing video > Continue a source clip beyond its current endpoint. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/video-extend - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.extend` - Dynamic model facts: call `beatra.models.list` with `capability: "video_extend"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Continue a source clip beyond its current endpoint. ## Primary agent path Use `beatra.videos.extend` to continue beyond a clip's current endpoint. Use edit instead when the existing timeline itself should change. 1. Upload the local source video. 2. Call `beatra.models.list` with `capability: "video_extend"` for current clip limits, final-duration rules, controls, and prices. 3. Describe only the continuation and any required final composition. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. ## Tool arguments ```json { "instruction": "Continue the camera move until the train enters the tunnel", "video": { "type": "artifact", "artifact_id": "artifact_source_clip" }, "direction": "after", "resolution": "720p", "duration": 12, "client_request_id": "vid-extend-opaque-1" } ``` `direction` is required (`after` continues past the end). `duration` means the final output duration, including the source clip—not the number of seconds to add. ## Models, controls, and cost Common controls are `prompt`, `negative_prompt`, `resolution`, `duration`, `aspect_ratio`, `seed`, `enhance_prompt`, and `watermark`. Use each only according to the selected model's metadata. Use `beatra.models.list` as the current source for selectable models, accepted source duration, final-duration range, resolution, derived aspect ratio, defaults, and price inputs. Ensure the final duration is valid for the source; never silently rewrite it. ### Wan 3.0 Set `model: "wan3.0-video"` or `wan3.0-video-prime`. `duration` is the final file length (2–30 seconds), must exceed the source by at least 2 seconds, and source seconds plus that duration must be at most 30. Source video is at most 15 seconds. Only `direction: "after"` is supported. Source seconds and the final file length both bill at the same rate: `480p` 225 credits/s (`wan3.0-video`) or 335 (higher tier). ## Task status and recovery Keep polling the same task while it is `queued` or `running`. Retry a lost create response only with identical arguments and the same `client_request_id`. A new source, instruction, model, or duration requires a new ID. ## REST API Direct protocol integrations use `POST /v1/videos/extend`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_extend_v1_videos_extend_post) for the complete request contract. Skill + MCP is the recommended integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Enhance a video prompt > Turn a creative brief and optional multimodal context into a production-ready video prompt. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/video-prompt-enhancement - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.videos.enhance_prompt` - Dynamic model facts: call `beatra.models.list` with `capability: "video_prompt_enhancement"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Turn a creative brief and optional multimodal context into a production-ready video prompt. ## Primary agent path Use `beatra.videos.enhance_prompt` when the user wants a more complete video prompt before deciding whether to generate a video. The task returns text only; it never starts video generation automatically. 1. Upload any local image, video, or audio context. 2. Provide the creative `prompt`, target `duration`, and `aspect_ratio`. 3. Optionally provide strict first/last frames or an ordered reference set, but never both modes in the same request. 4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`. 5. Review or edit the returned prompt before making a separate video request. ## Tool arguments ```json { "prompt": "A paper boat crosses a rain-filled neon street at night", "duration": 5, "aspect_ratio": "16:9", "client_request_id": "vid-prompt-opaque-1" } ``` `model` is a compatibility input for this first release. Missing, `auto`, or any other value or type is ignored and does not change request identity; Beatra resolves the available prompt-enhancement model internally. The target duration is 4–15 whole seconds. Accepted ratios are `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, and `9:16`; `adaptive` is available only when media gives the model a source ratio. Strict-frame mode accepts an optional first frame and an optional last frame. Reference mode accepts up to five images, three videos, three audio files, and eleven items in total. Each reference video or audio file must be 2–15 seconds, with no more than 15 seconds of each kind in total. ## Billing and task status This is an asynchronous postpaid task. A successful task is charged from the actual input and output tokens at 4,500 credits per million input tokens and 18,000 credits per million output tokens. Failed and canceled tasks are not charged. The task can therefore be accepted before the final charge is known; the terminal task records the settled amount. Poll the same task while it is `queued` or `running`. Reuse `client_request_id` only for an identical retry. A changed prompt, target, or reference set is a new logical request and needs a new ID. ## REST API Direct protocol integrations may use `POST /v1/videos/prompts/enhance`. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_enhance_prompt_v1_videos_prompts_enhance_post). Skill + MCP is the recommended agent integration; REST serves custom applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra MCP — Understand video > Analyze one bounded video with fixed sampling and per-second pricing. > Self-contained workflow guide for MCP clients and AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/video-understanding - Primary agent surface: authenticated MCP at `https://mcp.beatra.ai/mcp`. - Billable action: `beatra.videos.understand`. - Dynamic model facts: call `beatra.models.list` with `capability: "video_to_text"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. - Alternative application surface: REST/OpenAPI with a stable `Idempotency-Key`. This direct MCP capability does not depend on an installable Skill package. --- Video understanding is available through authenticated MCP and REST as a preview: the capability and price may change. Submit one bounded video and a prompt; Beatra returns a durable asynchronous task. ## MCP Call `beatra.videos.understand` with one stable `client_request_id`: ```json { "client_request_id": "understand-demo-01", "model": "auto", "prompt": "Summarize the sequence of events and the final outcome.", "video": { "type": "url", "url": "https://example.com/demo.mp4" }, "detail": "default", "response_format": "text" } ``` Use `beatra.models.list` with `capability: "video_to_text"` when current model, limit, or price facts matter. Submit the finalized arguments once, then poll the returned `task_id` with `beatra.tasks.get`. On success, the answer is in both `structuredContent.task.output.text` and the MCP text content. For a local video, call `beatra.assets.upload` with the exact MIME type and byte length, perform the returned HTTPS `PUT` with the raw bytes, and pass the returned `artifact_id` as the `video` input. The uploaded source remains in the account asset library. ## REST Send the same understanding fields, without `client_request_id`, to `POST /v1/videos/responses` and provide a stable `Idempotency-Key` header. Poll `GET /v1/tasks/{task_id}` until terminal. The video may be a in your account `artifact`, an external HTTPS `url`, or a base64 `data_uri`. External and inline inputs are validated, stored in the account's uploaded-material library, and passed to the model from Beatra's CDN. ## Contract - `prompt` is required and must contain non-whitespace text. - Exactly one `video` is accepted. - The decoded file is limited to 50 MiB and 360 seconds, inclusive. - Sampling is fixed internally at 1 fps. `fps` and frame-strategy controls are not public request fields. - `detail` accepts `default`, `low`, or `high`, defaults to `default`, and does not change price. - `thinking` is hidden and adaptive thinking is enabled internally. - `MiniMax-M3` is the current selectable model; live discovery remains authoritative. ## Billing Successful requests cost **0.4 credits per accepted input-video second**. Duration is rounded up to the next whole second, so 10.001 seconds bills as 11 seconds. Provider token usage does not change the customer charge. Failed tasks are not charged. Uploaded source material remains available in the account asset library; temporary server files used during ingestion are deleted after processing. --- ## Appendix: shared direct MCP contract ### Retry identity One logical understanding request has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. The task is authoritative for the resolved model, answer, usage quantity, and charged credits. Successful image understanding is billed by the number of images accepted; successful video understanding is billed by input-video seconds rounded up. Failed tasks are not charged. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Text to speech > Synthesize speech from text with a preset or cloned voice. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.speech.synthesize` - Dynamic model facts: call `beatra.models.list` with `capability: "text_to_speech"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Synthesize speech from text with a preset or cloned voice. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.speech.synthesize`. The tool is billable and returns an asynchronous task. 1. Pick a voice first: `beatra.voices.list` returns preset and cloned voices with `voice_id` and preview URLs. 2. If a model, language, format, or price matters, call `beatra.models.list` with `capability: "text_to_speech"`. Otherwise use `model: "auto"` or omit `model`. 3. Create one opaque `client_request_id` and submit the final arguments once. 4. Poll the returned task with `beatra.tasks.get` until it is terminal. ## Tool arguments ```json { "voice": "voice_01JX...", "input": "Welcome to Beatra — make your first call in three minutes.", "language": "en-US", "format": "mp3", "speed": 1.0, "client_request_id": "tts-opaque-1" } ``` `voice` accepts any `voice_id` from [voices](https://docs.beatra.ai/en/docs/capabilities/speech/voices), preset or [cloned](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone). A voice belongs to one engine (its `compatible_models`), and on some models what a voice follows differs from voice to voice; its `persona` says so. Streaming and real-time conversation are not part of this capability. ## Speech markup `input` may contain a closed set of tokens. Tokens count toward the selected model's `constraints.input_max_characters` limit and weighted-character billing. The live vocabulary and ranges are `constraints.script_markup` on the model card from `beatra.models.list`. The same markup works on every speech model; what a model cannot render is degraded (dropped or ignored) with a warning, never approximated. Malformed markup never fails a request either: what can be corrected is read as the canonical token, and the rest is dropped or read as written, with a `markup_adjusted` warning that gives the reason and the correct form. Only a request with markup but no text to read is rejected with 422 before charging, on every model. The model-specific options further down this page are `model_options` fields, not markup. - `{pause }` — silence, at most two decimal places, within the model card's `script_markup.pause.range` (up to 99.99 seconds on MiniMax, 10 seconds on Doubao; a longer pause is cut to the limit with a warning). Seconds may carry a unit: `{pause 500ms}`, `{pause 0.5s}`. ElevenLabs renders no pauses: it removes them with `markup_degraded` (see ElevenLabs v4 and v4 Turbo). A malformed pause (such as `{pause}` or `{pause abc}`) and a pause at the start or end of the text are dropped, and of adjacent pauses (no speakable text between them) only the first is kept, each with `markup_adjusted`. - Sound tags: `{laugh}` a laugh, `{chuckle}` a chuckle, `{sigh}` a sigh, `{breath}` an audible breath, `{cough}` a cough, `{clear-throat}` a throat clear, `{gasp}` a gasp, `{groan}` a groan, `{inhale}` an inhale, `{exhale}` an exhale, `{pant}` panting, `{sniff}` a sniff, `{hmm}` a hesitant "hmm". `script_markup.tags` lists the tags a model renders; on a model without them the tag is removed (never read aloud) and a `markup_degraded` warning says so. - `{pron }` — pin the reading of this one occurrence of a word; the same word elsewhere keeps its default reading, and one request may give the same character different readings. Readings are pinyin: syllables written together, each ending with a tone digit 1–5, `v` for ü, one syllable per Chinese character. Other notations are not supported. A malformed reading (missing, not pinyin, or a syllable count that does not match) reads the word as written, with `markup_adjusted`; syllables separated by spaces are joined. A reading in several parts where any part is not pinyin (usually a missing closing brace) keeps the whole group as text, with `unknown_markup`. Example: `孩子{pron 长 zhang3}大了,头发也很{pron 长 chang2}。` - `{sub }` — speak this occurrence of a word as the given text, up to 100 characters; subtitles still show the word. Use it for brand names, abbreviations, English words, and digits that must be read one by one. A missing spoken text reads the word as written, with `markup_adjusted`; a spoken text over 100 characters keeps the whole group as text, with `unknown_markup`. Example: `{sub W3C 万维网联盟}`. - `{{` — a literal left brace: a `{{` in the text is spoken as one `{`, and the pair itself is never parsed as a token. Text after it is still parsed normally, so escape only the left brace and write right braces as they are. - `{emotion }` — inline emotion: from this point on, speak with this emotion until the next `{emotion …}`. The request's `emotion` is the starting emotion, and the values are the same. Only models whose card has `script_markup.inline_emotion` follow it sentence by sentence; other models drop the marker, use `emotion` for the whole request, and return `markup_degraded` naming the models that support it, if any. An invalid value is dropped (never read aloud) with `markup_adjusted`. Example: `Let's go. {emotion happy}Look, the sea! {emotion sad}Too bad we leave tomorrow.` - Performance markers — apply to the sentence that follows and do not carry over to the next paragraph. The available markers are the model card's `script_markup.performance`; only models that list them perform them, and other models drop them with `markup_degraded` naming the models that do, if any. - A near-miss spelling is read as the canonical token (`{laughs}` and `{Laugh}` as `{laugh}`), with `markup_adjusted`; so is a known token in full-width braces (`{pause 1}`), while other full-width braces are plain text. Unknown brace content (such as `{name}`), and markup-like groups with something extra (`{pause: 1000}`, `{pause and think}`), stay in the text as written, with `unknown_markup`. Text in square or round brackets (`[laughs]`, `(softly)`) is customer text passed through unchanged; when it looks like a stage direction, `unrecognized_markup` says so; for emotion and performance words it suggests a canonical token only when the current model performs it. `constraints.limitations` on each model's card states that model's limits in plain sentences; read it for the model you call. Examples: - Volume, speed, and pitch apply to the whole request and cannot target one sentence or word; so does emotion, unless the card has `script_markup.inline_emotion`. For local variation, split into multiple calls (each with its own parameters and its own audio file) or rewrite the text (ellipses, short clauses, wording). - On some models, long texts (over 3,000 characters, which take the async path) do not get high-quality number normalization, or drop `{pause}` and `{pron}` markup (with a warning). Split long texts at paragraph breaks into requests of at most 3,000 characters when that matters. ## Performance direction and previous text Two optional fields describe how a clip should sound, on every model that follows them; the model card lists each one under `controls` (with `constraints.direction_max_characters` and `constraints.previous_text_tail_characters`): - `direction` — natural-language direction for the whole request, for example `像在耳边说悄悄话一样,轻声地说` or `read it like breaking news`. Keep it to a sentence or two: a direction longer than `direction_max_characters` is ignored with a warning. How it comes through depends on the model, the voice and the text; a volume request is better made with `volume`. - `previous_text` — the text that comes right before this clip (the previous line of a dialogue, the previous paragraph), so separately synthesized clips keep a continuous tone. Any length is accepted; the model uses only its last `previous_text_tail_characters` characters. It is never spoken. Neither field is billed, and neither ever makes a request fail. A model, a voice, or a path that does not follow a field ignores it and returns an `option_ignored` warning; the audio is still produced. On some models these controls depend on the voice (for example, character voices may follow neither); `constraints.limitations` on the card says which. `emotion` works the same way: a model or voice that cannot render the requested emotion ignores it with a warning. To learn whether a voice follows these controls before a billable call, send the same request to validate (below): it returns the same warnings, free. Before a billable submit, call `beatra.speech.validate` or `POST /v1/audio/speech/validate`. It runs the same checks and warnings and returns the weighted character count and the credit price; it does not create a task, charge credits, or call the speech engine. It does not take an `Idempotency-Key`. It does not check the two-task ElevenLabs limit or current capacity. Warnings, when present, are on the 202 response (including an idempotent replay), `GET /v1/tasks/{task_id}`, `beatra.tasks.get`, and the customer callback field `task.warnings`. The task list, `expand`, account detail, and admin responses do not promise them. `text_begin` and `text_end` in a subtitle file are offsets into the text the engine actually read — the text with markup compiled into the engine's own form or removed — and are not mapped back to the submitted text. ElevenLabs is the exception: its offsets point into your text with markup removed and each `{sub}` shown as its written word; without markup this is exactly the text you submitted. Where a subtitle segment lines up with that text, its `text` shows a `{pron}` or `{sub}` word as written and leaves sound tags out. Billing counts characters as described under [Models, controls, and cost](#models-controls-and-cost); `output.characters` reports the characters the engine read, so the two counts can differ. On ElevenLabs, `output.characters` is the billed weighted count. ## Models, controls, and cost Common controls are `input` (required; use the selected model's character limit), `voice` (required), `language`, `format` (default `mp3`; the card's `constraints.formats` lists the others the model renders), `speed` (0.5–2.0), `volume` (within the card's `constraints.volume` range, for example >0–10 or 0.5–2; a value outside it is rejected before billing), `pitch` (−1–1, normalized: 0 keeps the voice's original pitch, −1 the lowest, 1 the highest the selected model supports; use decimals like 0.25 for subtle tuning), `emotion`, `sample_rate`, and `subtitle_enable` (default `false`; set `true` to receive sentence-level subtitles with the audio as `output.subtitles` — free; a model that cannot time subtitles for the chosen voice or language rejects the request before billing, and `constraints.limitations` names those cases. MiniMax and Doubao may deliver audio without subtitles after a runtime subtitle failure; ElevenLabs requires the requested subtitles and fails with a refund if they cannot be delivered). `language` is a hint some models only partly use: `constraints.limitations` says how the selected model treats it. Use each only according to the selected model's metadata. Not every format supports every sample rate (for example `opus` renders at 8/16/24 kHz on some models and only at its fixed 48 kHz on others, where it takes no `sample_rate`): read `constraints.sample_rates_by_format` on the model card instead of assuming the flat rate list applies to every format. `beatra.models.list` is the current source for selectable models, supported languages, formats, sample rates, and prices. Do not copy a model catalog or price table into an agent prompt. Speech is prepaid from the request estimate and billed **linearly** by weighted characters (quoted per 1,000): each Han ideograph counts as 2 and every other code point counts as 1. The count is taken on the submitted text, markup included. On a model whose engine bills the control text it receives by length, the text sent to the engine is counted when it is longer: there, pauses and readings become control tags, and a request that carries them (or whose text begins with `` escaped). Validate returns the exact count. ## Model-specific options `model_options` carries options that only one model family runs, named by family. The model card lists the keys it runs under `controls` (for example `model_options.doubao.explicit_dialect`). Keys for another family have no effect; a model may say so with an `option_ignored` warning. ### MiniMax: pronunciation dictionary For rare or polyphonic Chinese characters, pin the exact reading instead of rewriting the text with a homophone: ```json { "model_options": { "minimax": { "pronunciation_dict": { "tone": ["湛/(zhan4)", "晞/(xi1)", "厌/(yan1)"] } } } } ``` The format is `character/(pinyin+tone digit)`, with tone digits 1–4 for the four tones and 5 for the neutral tone. A dictionary entry applies to every occurrence of the word in the request; to fix one occurrence, use the `{pron}` markup above. MiniMax models only; other models ignore this field. ### Doubao - `model_options.doubao.explicit_dialect` — `beijing`, `dongbei`, `henan`, `shaanxi`, `shanghai`, `sichuan` or `tianjin` (Cantonese is `language: "yue-HK"`). Only voices whose `languages_supported` lists `yue` speak dialects; other voices are rejected before billing. - `model_options.doubao.explicit_language` — forces the reading language (`zh-cn`, `en`, `ja`, `es-mx`, `ko`, `de`, `fr`, …). This is a filter, not a hint: sentences in other languages are skipped, and a voice given text it cannot read produces no audio (the task fails and is refunded). `nl`, `no`, `uk`, `fi`, `da`, `cs`, `hu`, `el`, `ro`, `hi` and `es-es` work only with Chinese (`zh_…`) preset voices. Long texts accept only `zh-cn`, `en`, `es-mx`, `id` and `pt-br`. - `model_options.doubao.silence_duration` — silence appended after the last word, 0–30,000 milliseconds. - `model_options.doubao.latex_parser` — `"v2"` reads LaTeX formulas aloud (education scripts). - `model_options.doubao.pronunciation_dict` — `{"tone": ["北京/(bei3)(jing1)", "omg/oh my god"]}`: up to 5,000 rules applied to every occurrence of the word (a reading, or a replacement text). To fix one occurrence, use `{pron}`. When the text uses `{pause}` or `{pron}`, the markup wins: `latex_parser` and `pronunciation_dict` are ignored with a warning, because the engine cannot combine them with the form that markup compiles to. ## Languages `language` is an optional provider-neutral BCP-47 tag such as `zh-CN`, `yue-HK`, or `en-US`. Beatra matches the primary language subtag against the selected model; omit the field to let the voice or provider choose. Pass the exact value `auto` only when you explicitly want automatic language detection (`constraints.language_auto` on the model card says whether the model supports it). An unsupported language is rejected instead of being silently replaced. How a model uses `language` differs. Some use it as a recognition hint for the voice. Others read Chinese and English by default and use `language` to turn on language recognition for anything else (a Chinese voice may read nothing in, say, Japanese without it) and to pick a dialect (`yue`); on those, each voice reads only the languages in its `languages_supported`. A `language` the voice does not speak comes back with an `option_ignored` warning, except where the result could only fail: Cantonese on a voice without it, or a long text in a language the voice cannot read, is rejected before billing. `constraints.limitations` on the card says which applies. Current speech models cover up to the 40 languages below, each model a part of them; `constraints.supported_languages` from `beatra.models.list` is the live, model-specific source. | Code | Language | Code | Language | | --- | --- | --- | --- | | `zh` | Chinese | `tr` | Turkish | | `yue` | Cantonese | `nl` | Dutch | | `en` | English | `uk` | Ukrainian | | `es` | Spanish | `th` | Thai | | `fr` | French | `pl` | Polish | | `ru` | Russian | `ro` | Romanian | | `de` | German | `el` | Greek | | `pt` | Portuguese | `cs` | Czech | | `ar` | Arabic | `fi` | Finnish | | `it` | Italian | `hi` | Hindi | | `ja` | Japanese | `bg` | Bulgarian | | `ko` | Korean | `da` | Danish | | `id` | Indonesian | `he` | Hebrew | | `vi` | Vietnamese | `ms` | Malay | | `fa` | Persian | `sk` | Slovak | | `sv` | Swedish | `hr` | Croatian | | `fil` | Filipino | `hu` | Hungarian | | `no` | Norwegian | `sl` | Slovenian | | `ca` | Catalan | `nn` | Nynorsk | | `ta` | Tamil | `af` | Afrikaans | ## ElevenLabs v4 and v4 Turbo `elevenlabs-v4` and `elevenlabs-v4-turbo` are open to every account and appear in the default model catalog, together with 80 preset voices (see [voices](https://docs.beatra.ai/en/docs/capabilities/speech/voices)). `elevenlabs-v4` is the most expressive of the two. `elevenlabs-v4-turbo` uses the same voices and languages, is faster, and costs about half. v4 keeps training, so the same voice can change over time, and the same `seed` is not guaranteed to reproduce after a model update. | Model | Credits per 1,000 weighted characters | | --- | ---: | | `elevenlabs-v4-turbo` | 240 | | `elevenlabs-v4` | 450 | An ElevenLabs voice with `model: "auto"` prefers Turbo among its compatible models. The model is fixed before admission; a failure never switches the voice or model. ### Length and counting A request accepts at most **10,000 characters**, counted as Unicode code points, for the original text and for the compiled text (markup applied) separately. Other engines accept up to 50,000. Over-limit input returns `422 invalid_request` before charging; shorten the text, use less markup, or drop `emotion`, and validate again. A request is never automatically split into several audio files. Every code point counts once for the limit, so a visible symbol can count more than one: - A Chinese character, a letter, or a single-code-point emoji counts 1. - Emoji sequences count every code point: 👍🏽 = 2, ❤️ = 2, 🇨🇳 = 2, 1️⃣ = 3, 👨‍👩‍👧‍👦 = 7. - Combining marks count separately: Devanagari vowel signs, Arabic diacritics, and decomposed accents each add one. Billing uses the same rule with weights: each Han ideograph counts 2 and every other code point counts 1. Credits are charged on the larger of the original text and the compiled text, both weighted. On ElevenLabs, `output.characters` is this billed weighted count. ### Formats, languages, and controls - Languages: `en`, `zh`, `ja`, `ko`, `es`, `pt`, `ar`, `hi`, `fr`, `it`. Omit `language` or use `auto` for automatic recognition; other explicit languages are rejected before charging. - Formats: MP3 at 22,050 / 24,000 / 44,100 Hz (default 44,100); WAV and raw PCM at 8,000 / 16,000 / 22,050 / 24,000 / 32,000 Hz (default 24,000); Opus at 48,000 Hz. Omit `sample_rate` for Opus. FLAC is unavailable. PCM results report `mime_type` `audio/L16` and a real `duration_seconds`. A very long WAV or PCM request whose audio would exceed the per-result size limit is rejected before charging with 422 `unsupported_option` on `format`; this applies only for long Chinese, Japanese or Korean text (about 7,500 characters or more) at 32,000 Hz. Use MP3 or Opus, a lower sample rate, or shorter text. - `direction` and nondefault `speed`, `volume`, or `pitch` are ignored with an `option_ignored` warning. - `emotion` supports the seven emotions other than `fluent`. Beatra adds an emotion tag (such as `[sad]`) at the start of each paragraph (paragraphs are separated by a blank line). The emotion starts at the tag and may fade over a long paragraph, so split long text with blank lines where it matters. The tags make the sent text longer, so they can raise the billed count (billing takes the larger of the submitted and the sent text), and they count toward the 10,000-character limit. `fluent` is ignored with `option_ignored`. All 13 sound tags (`{laugh}` and the rest) are supported and voice the sound where they are placed. Effects vary with the voice and the text; breathing sounds such as `{sigh}` and `{breath}` are light and may be hard to hear. - No pauses: `{pause}` is removed with `markup_degraded` (the card publishes [0, 0]); a malformed pause is dropped by the general rule, with `markup_adjusted`. `{pron}` is read as written, with `markup_degraded`. - Inline emotion works sentence by sentence: `{emotion }` inserts the emotion tag where it is written, and each later paragraph starts with the current emotion again. `fluent` is ignored with a warning, and later paragraphs get no emotion tag. Performance markers follow the card's `script_markup.performance`; both models perform all ten: `{whisper}`, `{shout}`, `{excited}`, `{sarcastic}`, `{curious}`, `{tearful}`, `{playful}`, `{nervous}`, `{tired}` and `{gentle}`. The tag goes right before the next spoken text and applies to the sentence that follows, never past the end of the paragraph. Inserted tags never appear in subtitles and count toward the sent text. - `{sub word spoken text}` speaks the replacement and shows the original word in subtitles. Square brackets you write are customer text: they are passed through unchanged and stay in subtitles; they are not Beatra markup. The engine may perform them as a sound or a style. - `subtitle_enable: true` promises sentence subtitles from measured character timestamps. ElevenLabs subtitle offsets (`text_begin`, `text_end`) point into your text with markup removed and each `{sub}` shown as its written word; without markup this is exactly the text you submitted. If valid subtitles cannot be built, the task fails and this synthesis is refunded; there is no audio-only success, and no paid transcription replaces missing timestamps. - `previous_text` and `model_options.elevenlabs.next_text` are context only and are never billed. Beatra sends the last 100 characters of the previous text and the first 100 of the next text. `model_options.elevenlabs` accepts `stability` and `similarity_boost` (finite numbers from 0 to 1), `seed` (integer 0–4,294,967,295), `next_text` (string), and `apply_text_normalization`. The model card's `constraints.limitations` lists the currently available normalization values. Both models currently enable only `auto`; `on` and `off` are ignored with a warning. Unknown keys are ignored with a warning; invalid values of known keys are rejected before charging. Before confirming a charge, validate the **complete final request**. Validate returns the weighted count and the price and checks the same syntax and limits, but it does not check the two-task limit or current capacity, so a request that validates can still receive the errors below. A 2,000-character clip took about one minute in testing; a 10,000-character clip may take several minutes. Keep polling the same task. ### Limits and errors Each account may have at most two ElevenLabs speech tasks in progress, across `elevenlabs-v4` and `elevenlabs-v4-turbo`. Free private [clone previews](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone) count toward the two; MiniMax and Doubao tasks do not. Errors before charge. Nothing is charged and no task is created, so a retry may reuse the same Idempotency-Key / `client_request_id` or use a new one. `voice_unavailable` is the exception: it is permanent and not retryable. | Error | `details.reason` | Meaning and what to do | | --- | --- | --- | | 429 `rate_limited` | `speech_inflight_limit` | Two ElevenLabs speech tasks are already in progress. Wait for one to finish. `retry_after_seconds` is 20; over REST a `Retry-After` header carries the same seconds (MCP has no headers; use `details.retry_after_seconds`). | | 503 `model_unavailable` | `voice_temporarily_busy` | The cloned voice is being prepared or restored. Retry after `retry_after_seconds` (about 30 seconds; a few minutes while a previous restore is being checked). | | 503 `model_unavailable` | `voice_temporarily_unavailable` | This cloned voice cannot be restored right now. Other voices are not affected. `available_at` gives the recovery time when known. | | 422 `invalid_request`, `unsupported_option`, `voice_unavailable`, or `voice_retired` | — | Fix the request, or see Voice retirement below and the clone page. | Errors after the task is accepted are task errors. All of them are refunded in full, and a later retry needs a new `client_request_id` or `Idempotency-Key`: | Task error | When | | --- | --- | | `model_rate_limited` | The model's capacity is full. | | `model_unavailable` | The model's allowance is used up; `available_at` gives the recovery time when known. | | `invalid_request` | The model rejected the text as too long. | | `model_output_invalid` | The model returned unusable audio. | | `voice_retired` | The voice retired after the request was accepted. | | `voice_unavailable`, or `model_unavailable` with reason `voice_temporarily_busy` / `voice_temporarily_unavailable` | A cloned voice could not be prepared at execution; same meaning as before charge, and the task is refunded. | ### Voice retirement A preset voice scheduled for retirement stays listed and usable until its date. The voice object then carries `retirement: {"retire_at": "", "replacement_voice_id": ""}`; the field is absent when nothing is scheduled. A synthesis with such a voice succeeds and carries a `voice_retiring` warning (Chinese text, field `voice`) with the date and the recommended replacement when known. After the date the request returns 422 `voice_retired` with `details.retirement_at` and, when known, `details.replacement_voice_id`. The check runs at admission and again at execution; a hit at execution fails the task and refunds it. The replacement is a suggestion: Beatra never substitutes a voice. A cloned voice that cannot be restored from its saved sample returns 422 `voice_unavailable`; this is permanent, so do not retry and contact support. The synthesis is not charged, and the clone fee is not refunded. ## Task status and recovery `queued` and `running` are not failures. Keep polling the same `task_id`; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same `client_request_id`. If any input changes, use a new ID. Failed tasks automatically refund the charged credits. Return the audio artifact, resolved model, and charged credits only from the terminal task response; artifact URLs are CDN addresses — copy them to your own storage promptly. ## REST API Direct protocol integrations may use `POST /v1/audio/speech` and the shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/audio/text_to_speech_v1_audio_speech_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Voice clone > Clone a reusable voice from an authorized audio sample. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.voices.clone` - Dynamic model facts: call `beatra.models.list` with `capability: "voice_clone"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Clone a reusable voice from an authorized audio sample. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.voices.clone`. The tool is billable, consent-gated, and returns an asynchronous task. 1. Confirm with the user that they hold the rights to this voice. Set `consent_attested: true` only after that explicit confirmation. 2. Upload the local sample with `beatra.assets.upload` and use its artifact ID. Each model's card lists its sample limits (the `sample_*` fields); a clean recording of one speaker works best. For ElevenLabs the sample must be 10 seconds to 5 minutes long and at most 20 MiB, in WAV, MP3, M4A, AAC, or OGG; anything outside these limits is rejected before charge. 3. Create one opaque `client_request_id` and submit the final arguments once. 4. Poll the returned task with `beatra.tasks.get`; the terminal response returns the new `voice_id`. ## Tool arguments ```json { "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." }, "display_name": "Brand narration - female", "consent_attested": true, "client_request_id": "voice-clone-opaque-1" } ``` `sample` accepts an artifact, HTTPS URL, or data URI. `display_name` is required (≤255 characters). A request without `consent_attested: true` is rejected. ## Optional quality prompt For a higher-similarity clone, add `prompt`: a short excerpt (shorter than 8 seconds) of the same voice plus its verbatim transcript. The engine aligns the excerpt character for character to sharpen the cloned timbre — useful when the main sample is long or slightly noisy. ```json { "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." }, "prompt": { "sample": { "type": "artifact", "artifact_id": "artifact_prompt..." }, "text": "Verbatim transcript of the prompt excerpt." }, "display_name": "Brand narration - female", "consent_attested": true, "client_request_id": "voice-clone-opaque-1" } ``` `prompt.sample` accepts the same reference kinds as `sample`; `prompt.text` (≤2,000 characters) must match the excerpt exactly and end with a punctuation mark. An excerpt measured at 8 seconds or longer, or a transcript without ending punctuation, is rejected before billing. Omit `prompt` to clone from the main sample only — the prompt adds no extra charge. ## Models, controls, and cost Omit `model` (or use `auto`) unless the user names one. `beatra.models.list` with `capability: "voice_clone"` is the current source for selectable models, accepted sample kinds, and the fixed price. With `auto` (and every model whose card sets `constraints.automatic_formal_activation: true`), voice cloning has one fixed charge when the activated voice is created successfully. Success means Beatra already ran a short formal synthesis to activate the clone — that activation is included in the charge; later speech synthesis is billed separately. A failed clone or activation does not retain the charge. ## Models that need a separate activation Some models are explicit-only: they are not in the default list, `auto` never picks them, and `beatra.models.list` lists them only when called with `include_activation_required: true` (REST: `GET /v1/catalog/capabilities/voice_clone?include_activation_required=true`). Their cards set `constraints.automatic_formal_activation: false`. That listing rule does not tell you whether activation is needed. `doubao-voice-clone-2.0` below clones in two steps: cloning makes a free preview, and a separate paid activation makes the voice usable for speech. The ElevenLabs clone is listed the same way but is one-step and ready on success (see the ElevenLabs section). Use an explicit-only model only when the user asks for it by name. `doubao-voice-clone-2.0`: - `language` is required and must be the language spoken in the sample: `zh`, `en`, `ja`, `ko`, `es`, `es-MX`, `pt`, `pt-BR`, `id`, `ms`, `th`, `vi`, `fil`, `de`, `fr`, `ru` or `ar`. A missing or unlisted value is rejected with 422 `unsupported_option`. - The sample must be WAV, MP3, OGG, M4A or AAC audio of at most 10 MiB, or it is rejected with 422 `voice_sample_rejected` before anything is charged. 14–30 seconds of one person speaking works best; by default only the first 25 seconds are used. `prompt` is ignored with an `option_ignored` warning. - Cloning and the preview are free. The task succeeds with `output.status: "pending_activation"`, a `preview` (a fixed sentence in the chosen language read in the cloned voice), `activation.price_credits`, `activation.quote` (the activation quote, see below), and `expires_at`. Play the preview to the user. - A waiting voice cannot be used for speech: synthesis returns 422 `voice_activation_required`. It can be renamed but not made the default. If it is not activated by `expires_at` (normally 7 days after cloning), it becomes `expired` (422 `voice_preview_expired`) and the voice must be cloned again. - Limits per account: 10 voices waiting for activation (409 `voice_limit_reached`; activate or delete one), 20 clones per UTC day (429 `rate_limited`, `details.reason: voice_training_daily_limit`), and one clone in progress at a time (429 `rate_limited`, `details.reason: voice_training_in_progress`; retry when it finishes). While cloning is busy for everyone the reason is `voice_training_busy`; retry after about 30 seconds. Optional `model_options.doubao` tunes the training. Values are checked before anything is charged; an unknown key or a value out of range is rejected with 422 `unsupported_option`. | Key | Type and range | Effect | | --- | --- | --- | | `sample_text` | string, at most 1,000 characters | The words spoken in the sample. A sample whose speech differs too much is rejected (`voice_sample_rejected`, `details.reason: sample_text_mismatch`). Checked for `zh`, `en`, `ja`, `ko`, `es`, `es-MX`, `pt`, `pt-BR`, `id`, `fr` and `ru` only; ignored with an `option_ignored` warning for the other languages. | | `enable_audio_denoise` | boolean (default `false`) | Remove background noise before training. | | `enable_audio_denoise_with_snr` | boolean | Remove noise only when the sample's signal-to-noise ratio is below `denoise_max_snr_thresh`. | | `denoise_max_snr_thresh` | integer, 1–99 (default 50) | The signal-to-noise ratio below which noise is removed. | | `reject_min_snr_thresh` | number, greater than 0 and less than 100 (default 5) | Reject a sample whose signal-to-noise ratio is lower. | | `voice_clone_denoise_model_id` | `SpeechInpaintingV2` (default) or `VocalDiffusionV2VocalDiffusionV2_44k` | The noise-removal model. | | `voice_clone_enable_mss` | boolean | Separate the voice from background music before training. | | `enable_crop_by_asr` | boolean | Pick the training segment by speech recognition instead of taking the first 25 seconds. | | `enable_check_prompt_text_quality` | boolean | Check the quality of `sample_text` before training. | | `enable_check_audio_quality` | boolean | Check the sample's audio quality before training. | | `disable_volume_normalization` | boolean | Keep the sample's recorded volume. | ```json { "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." }, "display_name": "My voice", "model": "doubao-voice-clone-2.0", "language": "zh", "model_options": { "doubao": { "enable_audio_denoise": true } }, "consent_attested": true, "client_request_id": "voice-clone-opaque-2" } ``` ## Activating a voice `beatra.voices.activate` makes a waiting voice usable for speech. The clone result already carries the quote, so one call activates: 1. The clone result's `activation.quote` carries `price_credits`, `balance_credits`, `sufficient_balance`, the `preview`, `terms` in `zh`, `en` and `ja`, `terms_version`, a `confirmation_token`, and `token_expires_at` (24 hours). 2. Tell the user the price and the terms and get their explicit consent. Never activate automatically. 3. Call it with `voice_id`, `confirmation_token` and `confirm_credits` (the quoted `price_credits`). The price is charged once and the call returns an asynchronous task; poll it with `beatra.tasks.get`. When it succeeds the voice is `ready`; its output carries the voice, with a final preview when one could be made. Called without `confirmation_token` (the token is gone or older than 24 hours), it returns a new quote and charges nothing. ```json { "voice_id": "voice_01JX...", "confirmation_token": "", "confirm_credits": 100000, "client_request_id": "voice-activate-opaque-1" } ``` - An expired token, a price that changed, or a `confirm_credits` that differs from the quote returns 422 `price_confirmation_required` with a new quote in `details.quote`; nothing is charged. Show the new quote and ask again. - A failed activation is refunded automatically; a successful one is not refunded. An activated voice cannot take a new recording: to change it, clone a new voice and activate that one. - Limits per account: one activation in progress at a time (429 `rate_limited`, `details.reason: voice_activation_in_progress`) and 3 activations per UTC day. A fourth returns 429 `voice_activation_daily_limit`: nothing is charged, and the user is asked to contact support. - When activation cannot run, the error is `internal_error`, nothing is charged (or the charge is fully refunded), and the message asks the user to contact support with the `request_id`. - Calling it for a voice that is already `ready`, including every voice cloned with `auto` and every preset voice, charges nothing and changes nothing. - While an activation runs, the voice cannot be deleted (409 `conflict`, `details.reason: voice_operation_in_progress`). The price is in the clone card (`pricing`, `billing_basis: successful_activated_voice`) and in every quote. Deleting an activated voice cannot be undone and the activation charge is not refunded; speech tasks already submitted for it still finish. An activated Doubao clone speaks with `doubao-seed-tts-2.0`, long text included, in the language it was trained in. A `language` it does not read (for a Chinese clone, anything other than Chinese, English or `auto`) gets an `option_ignored` warning that names the language the voice was cloned from, and a Chinese clone refuses it on the long-text path (send parts of up to 3,000 characters, or clone a voice from a recording in that language); the text itself is not checked. Subtitles, pauses, and readings follow the rules of a preset voice in that language. `emotion`, `direction`, and `previous_text` are sent to the model as for the voices that follow them; how they come through depends on the Doubao model. ## ElevenLabs: explicit, ready-on-success cloning `elevenlabs-voice-clone` is open to every account but explicit-only: pass `model: "elevenlabs-voice-clone"`. It is not in the default voice clone list and `auto` never picks it. Find it with `beatra.models.list` and `include_activation_required: true` (REST: `GET /v1/catalog/capabilities/voice_clone?include_activation_required=true`), with `GET /v1/catalog/models/elevenlabs-voice-clone`, or in the full `/v1/models` list. It matches the listing conditions of the two-step models above, but it is one-step: the voice is ready as soon as the task succeeds. A successful clone costs **7,270 credits once** and is immediately `ready` for `elevenlabs-v4-turbo` and `elevenlabs-v4`. The cloned voice works only with those two models and speaks the 10 languages they support (`en`, `zh`, `ja`, `ko`, `es`, `pt`, `ar`, `hi`, `fr`, `it`). The clone task creates the voice only: it does not synthesize speech, generate a preview, or require activation. A later speech request is separately quoted and charged. Calling activate on an already ready voice is a free no-op. `prompt` and `model_options` are ignored with a warning. **Sample limits.** These are limits, not recommendations; a sample outside them is rejected before any charge: - Format: WAV, MP3, M4A, AAC, or OGG. Another format returns 422 `unsupported_option`. - Length: at least 10 seconds and at most 5 minutes. Size: at most 20 MiB. A duration or size outside the range returns 422 `invalid_request`. - Use an authorized recording of one speaker. 1–2 minutes is recommended; more than 3 minutes does not improve the clone. If the engine itself rejects the sample after the task is accepted, the task fails with `voice_sample_rejected` and is refunded in full. The message says whether the sample was too short, too long, unreadable, or too large, or whether the voice needs additional verification (this also fails with `voice_sample_rejected` and is refunded). **Daily limit.** At most 3 ElevenLabs clones per account per UTC day; the day resets at 08:00 Beijing time (00:00 UTC). A clone counts when it is in progress, succeeded, or failed after reaching the engine. A sample rejected by the local checks above, or a clone canceled before upload, does not count. The fourth returns 429 `rate_limited` with `details.reason: voice_creation_daily_limit`, `retry_after_seconds`, and, over REST, a `Retry-After` response header with the same seconds (MCP has no headers); nothing is charged. Omit `model` to use the default voice clone at the same price. Replaying the same request does not create another clone. **Temporary errors.** Nothing is charged for either: - 503 `model_unavailable` with `details.reason: creation_temporarily_unavailable`: new clones with this model are paused. Omit `model` to use the default voice clone at the same price, or try again after `available_at` when it is given. - 503 `model_unavailable` with `details.reason: voice_temporarily_busy`: voice cloning is busy; retry after `retry_after_seconds` (about a minute). **Free preview.** When you explicitly select the free preview in the account or desktop interface, Beatra synthesizes a fixed sentence in your cloned voice and saves it for later playback. The sentence is chosen by the clone's `language` (one of the 10 languages, otherwise English). The first preview is free, is cached and reused, and counts toward the two-task ElevenLabs speech limit (see [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech)). If the voice must first be restored, the preview may return 503 `model_unavailable` (see `details.reason` and `retry_after_seconds`; for a restore in progress, `voice_temporarily_busy` with 30 seconds); the restore continues in the background and the next try succeeds. No preview is generated while two ElevenLabs speech tasks are already running; it simply returns no preview. A failed preview does not change the clone's result or charge. Custom text or different synthesis settings require a separately confirmed speech quote. **Your sample and the voice.** Clones remain owned by the account under the same `voice_id`. The uploaded sample is kept as a private copy so the voice can be restored internally when needed; restoring may add time and does not promise identical waveforms after model changes. The sample is deleted, together with the voice at the engine and any cached preview, when you delete the voice or close the account. Deletion cannot be undone and does not refund the clone; speech tasks already accepted still finish. A speech request on a cloned voice can fail in these ways. A temporarily busy voice (503 `voice_temporarily_busy`) or one that cannot be restored right now (503 `voice_temporarily_unavailable`, with `available_at` when known) is not charged and does not affect other voices. A voice that can no longer be restored from its saved sample returns 422 `voice_unavailable`: this is permanent, so do not retry; contact support. That synthesis is not charged, and the original clone fee is not refunded. A failed accepted speech request refunds only that speech charge. ## Task status and recovery `queued` and `running` are not failures. Keep polling the same `task_id`; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same `client_request_id`. If any input changes, use a new ID. The returned `voice_id` works directly as the `voice` field in [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech) once the voice is `ready` (a voice that needs activation, after it is activated), stays valid long-term, and can be inspected or deleted in [voices](https://docs.beatra.ai/en/docs/capabilities/speech/voices). ## REST API Direct protocol integrations may use `POST /v1/voices`, `POST /v1/voices/{voice_id}/activate`, and the shared task endpoints. Follow the generated API operations: [clone](https://docs.beatra.ai/en/docs/api-reference/operations/voices/clone_voice_v1_voices_post) · [activate](https://docs.beatra.ai/en/docs/api-reference/operations/voices/activate_voice_v1_voices__voice_id__activate_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Voices > List, inspect, and delete the voices available for speech synthesis. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/speech/voices - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Actions: `beatra.voices.list, beatra.voices.update` (non-billable read and management tools). - Interaction model: call `beatra.voices.list` to browse preset and cloned voices, and pass the selected `voice_id` into `beatra.speech.synthesize`. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- List, inspect, and delete the voices available for speech synthesis. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.voices.list`. It is a non-billable, read-only call that returns preset and in your account cloned voices. 1. Filter by `category` (`preset` / `cloned`), `language` (BCP-47), `gender` (`male` / `female` / `neutral`), `age_group` (`child` / `youth` / `adult` / `senior`), `use_case` (one of `audiobook`, `narration`, `news`, `ads`, `conversational`, `business`, `character`, `ivr`, `course`, `podcast`, `gaming`, `shorts`, `education`, `support`, `social`), `model` (a compatible model id), `query` (text in the display name), `search` (text in the display name or the persona), or `voice_id` (one exact voice). `status` picks which voices are listed: `ready` (the default: voices usable for speech), `pending_activation` (cloned previews waiting for a paid activation), `expired`, or `any`. 2. The list is paged: `limit` (1–500, default 50) and `cursor` (the `next_cursor` of the previous page). `total_count` is the number of voices that match the filters; `next_cursor` is `null` on the last page. 3. Use the returned `voice_id` directly as the `voice` field in [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech). `persona` describes the voice in one sentence, and `preview_url` (a general sample) and `preview_url_scene` (a sample in the voice's main use case) let the user listen before choosing; both samples are free. ## Tool arguments ```json { "category": "preset", "language": "zh-CN", "use_case": "audiobook", "age_group": "adult", "limit": 50 } ``` A voice entry looks like: ```json { "voice_id": "voice_preset_niannian", "display_name": "念念", "category": "preset", "language": "zh", "gender": "female", "age_group": "adult", "use_case": ["audiobook", "narration"], "persona": "温柔细腻的女声,适合有声书与旁白。", "preview_url": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian.mp3", "preview_url_scene": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian_scene.mp3", "compatible_models": ["minimax-speech-2.8-hd", "minimax-speech-2.8-turbo"], "status": "ready" } ``` A voice cloned with a model that needs a separate activation (see [voice clone](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone)) also carries `clone_model`, and while it waits for activation, its `preview` (`url`, `text`, `language`, `version`) and `expires_at`. Every other voice is unchanged. When the default (`ready`) list leaves out voices that wait for activation, its text summary says how many. `compatible_models` lists the speech models that can speak the voice. Each voice belongs to one engine, so leave `model` as `auto` (it picks from this list) or pass one of these models; another model is rejected before billing with `voice_model_incompatible`. The response also carries `next_cursor` and `total_count`. Over REST, `GET /v1/voices` takes the same filters as query parameters, with `q` in place of `query`. ## ElevenLabs voices Beatra has 80 ElevenLabs preset voices, `voice_preset_elevenlabs_001` to `voice_preset_elevenlabs_080`, open to every account. Each voice speaks one language: | Language | Presets | | --- | ---: | | `en` | 30 | | `es` | 12 | | `pt` | 8 | | `zh` | 7 | | `ar` | 6 | | `ko` | 5 | | `hi` | 4 | | `fr` | 3 | | `it` | 3 | | `ja` | 2 | - Every preset works with both `elevenlabs-v4` and `elevenlabs-v4-turbo`, and `model: "auto"` picks Turbo. - Presets sort after the existing presets, so the default first page may not show them. Find them with `model: "elevenlabs-v4-turbo"`. - `preview_url` and `preview_url_scene` are fixed Turbo renders. Personas follow the catalog convention and are written in Chinese. - A preset scheduled for retirement stays listed until it retires. Its entry then carries `retirement: {"retire_at": "", "replacement_voice_id": ""}`; the field is absent when nothing is scheduled. See [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech) for the `voice_retiring` warning and the `voice_retired` error. - A cloned ElevenLabs voice (see [voice clone](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone)) is `ready` as soon as it is created and works with the same two models. Deleting it also deletes the saved sample, the voice at the engine, and any cached preview. Deletion cannot be undone and does not refund the clone; speech tasks already accepted still finish. ## Default voice and renaming `beatra.voices.list` returns a `default_voice_id` next to `voices`: the account's default voice, or `null` when none is set. Each voice entry is unchanged. When the user asks for it, `beatra.voices.update` renames one of the account's cloned voices or makes any voice (cloned or preset) the default. It is non-billable and cannot delete a voice. A voice waiting for activation can be renamed, but only a `ready` voice can become the default. ```json { "voice_id": "voice_01JX...", "display_name": "Dr. Peng", "make_default": true } ``` ## Deleting a cloned voice Deletion is REST-only: ```bash curl -X DELETE "$BEATRA_BASE_URL/voices/voice_01JX..." \ -H "Authorization: Bearer $BEATRA_API_KEY" ``` Returns `204`. Only voices you cloned yourself can be deleted; preset voices cannot. Deleting a voice cloned with a model that needs activation is final. A voice waiting for activation (or expired) is removed with its preview. For an activated voice, the activation charge is not refunded, and speech tasks already submitted for it still finish. While an activation is running, the delete returns 409 `conflict` with `details.reason: voice_operation_in_progress`; try again once that task ends. ## REST API Direct protocol integrations may use the voice endpoints directly: [List](https://docs.beatra.ai/en/docs/api-reference/operations/voices/list_voices_v1_voices_get) · [Retrieve](https://docs.beatra.ai/en/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) · [Delete](https://docs.beatra.ai/en/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Text to music > Generate full songs with vocals or instrumental tracks from text prompts and lyrics. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/music/text-to-music - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.music.generate` - Dynamic model facts: call `beatra.models.list` with `capability: "text_to_music"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Generate full songs with vocals or instrumental tracks from text prompts and lyrics. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.music.generate`. The tool is billable and returns an asynchronous task. 1. Settle the outcome: vocal song or instrumental, mood, and whether the user supplies lyrics. 2. If a model, control, constraint, or price matters, call `beatra.models.list` with `capability: "text_to_music"`. Otherwise use `model: "auto"` or omit `model`. 3. Create one opaque `client_request_id` and submit the final arguments once. 4. Poll the returned task with `beatra.tasks.get` until it is terminal. ## Tool arguments ```json { "prompt": "Upbeat city pop for a summer evening drive", "instrumental": false, "lyrics": "Evening wind sweeps across the rooftop\nNeon lights flicker on one by one", "client_request_id": "music-text-opaque-1" } ``` `instrumental: true` generates instrumental-only music and forbids `lyrics`. ## Models, controls, and cost Common controls are `prompt`, `lyrics`, `instrumental`, `title`, and `model_options`. Use each only according to the selected model's metadata. `beatra.models.list` is the current source for selectable models, prompt and lyrics length limits, vocal-lyrics requirements, model-family options, and the per-task price. Do not copy a model catalog or price table into an agent prompt. Model-family options under `model_options.*` require an explicit `model`; unsupported combinations fail validation instead of being silently ignored. Music is prepaid and billed per successful task at the selected model's catalog price. ### Suno 6 & MiniMax Music 3.0 Selectable text-to-music models include **Suno 6** (`suno-v6`, `suno-v5.5`, `suno-v5`, `suno-v4.5`) and **MiniMax Music 3.0** (`minimax-music-3.0`, `minimax-music-2.6`). Both families support full vocal songs with structured section tags (`[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`) as well as instrumental-only generation (`instrumental: true`). Check `beatra.models.list` with `capability: "text_to_music"` for live per-track credit pricing and model-specific `model_options`. ## Task status and recovery `queued` and `running` are not failures. Keep polling the same `task_id`; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same `client_request_id`. If any input changes, use a new ID. Failed tasks automatically refund the charged credits. A successful task returns one or more `clips[]`, each with a title, optional lyrics, and an audio artifact. Artifact URLs are CDN addresses — copy them to your own storage promptly. ## REST API Direct protocol integrations may use `POST /v1/music/text-to-music` and the shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/music/text_to_music_v1_music_text_to_music_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra Skill + MCP — Reference audio to music > Generate new music based on the style of a reference audio clip. > Self-contained workflow guide for AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/music/reference-audio-to-music - Primary surface: the Universal Beatra Skill with authenticated MCP. - Install or reconnect: https://beatra.ai/install.md - MCP endpoint: `https://mcp.beatra.ai/mcp` - Billable action: `beatra.music.generate` - Dynamic model facts: call `beatra.models.list` with `capability: "reference_audio_to_music"` only when model constraints, controls, or prices matter. - Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal. - Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response. REST/OpenAPI is the fallback protocol path, not the primary agent packaging. --- Generate new music based on the style of a reference audio clip. ## Primary agent path Use the Universal Skill with the MCP tool `beatra.music.generate` and a `reference_audio` input. The tool is billable and returns an asynchronous task. 1. Upload local reference audio with `beatra.assets.upload` and use its artifact ID; an artifact from any successful Beatra music task also works directly. 2. If a model, reference constraint, or price matters, call `beatra.models.list` with `capability: "reference_audio_to_music"`. Otherwise use `model: "auto"` or omit `model`. 3. Create one opaque `client_request_id` and submit the final arguments once. 4. Poll the returned task with `beatra.tasks.get` until it is terminal. ## Tool arguments ```json { "prompt": "Keep the groove of the reference track, shift it to a festive mood", "reference_audio": { "type": "artifact", "artifact_id": "artifact_01JX..." }, "client_request_id": "music-cover-opaque-1" } ``` `reference_audio` accepts an artifact, HTTPS URL, or data URI. ## Models, controls, and cost Common controls are `prompt`, `reference_audio`, `lyrics`, `instrumental`, `title`, and `model_options`. Use each only according to the selected model's metadata. `beatra.models.list` is the current source for selectable models, reference duration/size/format limits (`constraints.reference_audio`), prompt and lyrics limits, and the per-task price. Do not copy a model catalog or price table into an agent prompt. Not every control is available on every model — an instrumental reference-audio request, for example, requires a model that supports it. Unsupported combinations fail validation instead of being silently ignored. Music is prepaid and billed per successful task at the selected model's catalog price. ## Task status and recovery `queued` and `running` are not failures. Keep polling the same `task_id`; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same `client_request_id`. If any input changes, use a new ID. Failed tasks automatically refund the charged credits. A successful task returns the same `clips[]` structure as [text to music](https://docs.beatra.ai/en/docs/capabilities/music/text-to-music) (`output.type` is `reference_audio_to_music`). Artifact URLs are CDN addresses — copy them to your own storage promptly. ## REST API Direct protocol integrations may use `POST /v1/music/reference-audio-to-music` and the shared task endpoints. Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/music/ref_audio_to_music_v1_music_reference_audio_to_music_post). Skill + MCP is the recommended integration; use REST for custom, non-agent applications. --- ## Appendix: shared Skill + MCP contract ### Retry identity One logical generation has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any prompt, media, model, or output control changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. Only the task response is authoritative for the resolved model, artifacts, charged credits, and refunded credits. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; refresh current constraints with `beatra.models.list` after model validation; request a new upload grant after expiration or MIME/length mismatch. Changed generation arguments always require a new `client_request_id`. --- # Beatra MCP — Public social data > Search public social content, read posts, creators, comments, and engagement, then continue into Beatra understanding and creation. > Self-contained workflow guide for MCP clients and AI agents. > Human-readable page: https://docs.beatra.ai/en/docs/capabilities/social - Primary agent surface: authenticated MCP at `https://mcp.beatra.ai/mcp`. - Discover tools: `beatra.social.tools.search` then `beatra.social.tools.get`. - Billable action: `beatra.social.execute`. - Interaction model: copy `schema_hash` from `tools.get`, create one opaque `client_request_id`, submit once, then poll `beatra.tasks.get` until terminal. - This capability has no model field and no public REST API. This MCP capability does not depend on an installable Skill package. --- Search public social content, read posts, creators, comments, and engagement, then continue into Beatra understanding and creation. ## Primary agent path Public social data uses the **same** Beatra OAuth MCP connection as images, video, music, and speech. You do not add a second server. Connect `https://mcp.beatra.ai/mcp`, then: 1. Search available tools with `beatra.social.tools.search` — by platform, keyword, or type (`content`, `creator`, `comments`, `trends`, `captions`). 2. Inspect one tool with `beatra.social.tools.get`. Confirm the credit price, then copy the returned `schema_hash` and argument list. 3. Call `beatra.social.execute` once with `operation_key`, that `schema_hash`, `arguments`, and one `client_request_id`. 4. Poll `beatra.tasks.get` until the task is terminal. The result is inline JSON or a JSON artifact. One `execute` is one prepaid task and one lookup. The next page of a list is another `execute`. ## Tool arguments ```json { "operation_key": "social.tiktok.video.get_by_id", "schema_hash": "sha256:…", "arguments": { "aweme_id": "…" }, "client_request_id": "social-lookup-opaque-1" } ``` Use the `schema_hash` that `beatra.social.tools.get` just returned. If get returns a new hash, send a new `client_request_id`. ## What you can look up See `beatra.social.tools.search` and `beatra.social.tools.get` for the live tool list, arguments, `schema_hash`, and credit price. Typical successful payloads include: - post or note text, author identity, and public statistics - comment and reply text with public engagement counts - captions or subtitles when the selected tool returns them - **public media URLs** (play, cover, image) you can fetch or pass to `beatra.images.understand`, `beatra.videos.understand`, or a generation tool Small results are inlined on the task. Larger results are stored as a JSON artifact and linked from the task. Open Activity in the console to read the same payload. ## Price Each successful lookup costs one of these credit amounts, confirmed before the task is created: | Credits per successful lookup | | --- | | 6 | | 12 | | 30 | | 60 | Failed or safely canceled tasks refund the hold. After the lookup has started, cancel returns `409` — keep polling the same task. Social tasks have no `model` field. ## Billing, task status, and recovery `queued` and `running` are not failures. If the create response is lost, retry the identical arguments with the same `client_request_id`. Any changed argument requires a new ID. | Situation | What to do | | --- | --- | | `402 insufficient_balance` | Top up at [console.beatra.ai](https://console.beatra.ai), then retry the same `client_request_id`. Nothing was charged. | | `invalid_request` on arguments | Call `beatra.social.tools.get` and send only the published fields. | | Tool not found or not available | Search again; use an `operation_key` that `tools.get` reports as available. | | `schema_hash` no longer matches | Call `tools.get` again and submit a new `client_request_id`. | | Lost create response | Retry the identical execute with the same `client_request_id`. | | `409` on cancel | The lookup already started. Keep polling the same task. | When a lookup fails after it started, keep the error `code` and read `error.message`. That message is the platform's wording after safety redaction. Change arguments only when the message names a field or ID; otherwise wait or keep polling the same task. ## REST API There is no public Social REST API. Use MCP plus `beatra.tasks.get`. --- ## Appendix: shared social MCP contract ### Retry identity One logical social lookup has one `client_request_id`. If the create response is lost, retry the exact same arguments with that ID. If any tool, `schema_hash`, or argument changes, use a new ID. Never create another paid task merely because the first task is `queued` or `running`. ### Polling and billing truth Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`, `failed`, or `canceled`. The task is authoritative for the JSON result or artifact, charged credits, and refunded credits. A successful lookup is billed at the credit price returned by `beatra.social.tools.get`. Failed or safely canceled tasks refund the hold. ### Recovery Preserve structured Beatra error codes. Reconnect on authentication failure; stop and request a balance action on insufficient balance; call `beatra.social.tools.get` again after `schema_hash` or argument validation fails. When a lookup fails after it started, keep the error `code` and read `error.message` — that message is the platform wording after safety redaction. Change arguments only when the message names a field or ID; otherwise wait or keep polling the same task. Changed arguments always require a new `client_request_id`.