# Enhance a video prompt
> Turn a creative brief and optional multimodal context into a production-ready video prompt.

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.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/videos-video-prompt-enhancement.md

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