# Animate an image
> Turn one still image into motion, optionally following driving audio.

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

AI integration guide: https://docs.beatra.ai/llms/videos-image-to-video.md

## Tool arguments

```json
{
  "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.

```json
{
  "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](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_i2v_v1_videos_image_to_video_post).
Skill + MCP is the recommended integration; REST serves custom applications.