Enhance a 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

Tool arguments

{
  "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. Skill + MCP is the recommended agent integration; REST serves custom applications.