Animate an image

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.

AI guide

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

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