Animate an image

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.

Upload a local image and optional local audio with beatra.assets.upload.
Call beatra.models.list with capability: "image_to_video" when model constraints, audio support, or price matter.
Describe motion and camera behavior without contradicting the source image.
Submit once with one client_request_id, then poll with beatra.tasks.get.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

{
  "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 customer 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, the output is 2K, duration is 4–15 seconds, and the output ratio is derived from the input image. H3 accepts watermark but not driving audio or the other optional controls. The input image is free and generated output costs 590 credits per second.

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