# 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.

---

## 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 admitted 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`.