# 让图片动起来
> 将一张静态图片变成动态视频，并可选用驱动音频。

将一张静态图片变成动态视频，并可选用驱动音频。

## Agent 主路径

当一张图片定义开场画面时使用 `beatra.videos.animate`。如果首帧和尾帧都
必须受控，应改用 `beatra.videos.interpolate`。

1. 用 `beatra.assets.upload` 上传本地图片与可选音频。
2. 当模型约束、音频能力或价格重要时，以
   `capability: "image_to_video"` 调用 `beatra.models.list`。
3. 描述运动和镜头行为，不要与源图冲突。
4. 使用一个 `client_request_id` 只提交一次，再用
   `beatra.tasks.get` 轮询。

## AI 指南

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

## 工具参数

```json
{
  "prompt": "人物转向镜头，摄影机缓慢向前推进",
  "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` 可省略。图片也可使用公开 HTTPS `url`，或完整编码值不超过
256KB 的 `data_uri`；更大的媒体必须先上传并使用 artifact。本地文件路径不能
直接传给远程 MCP。

## 模型、控制与成本

通用控制项包括 `prompt`、`negative_prompt`、`resolution`、
`duration`、`aspect_ratio`、`seed`、`enhance_prompt` 和 `watermark`；
每一项都应按所选模型的元数据使用。

以 `beatra.models.list` 返回的媒体组合、音频限制、分辨率、时长、输入图
派生宽高比规则、默认值和价格为准。分辨率和时长通常影响成本，不得
静默降低。除非用户明确指定可选模型，否则使用 `auto`。

### MiniMax H3

设置 `model: "minimax-h3"` 可用 MiniMax H3 动画化图片。提示词必填，时长为
4–15 秒，宽高比由输入图片派生。公共 `720p` 输出每秒 370 积分，`2k`
输出每秒 590 积分；显式选择 H3 并省略分辨率时默认 720p。H3 支持
`watermark`，但不接受驱动音频或其他可选控制项。输入图片免费。

### Wan 3.0

设置 `model: "wan3.0-video"` 或 `wan3.0-video-prime`。时长 2–30 秒，宽高比跟随图片。
不要传 `driving_audio`（不能与首帧混用）。`480p` 为每输出秒 225 / 335 积分（标准版 / 高阶版）。

## 保存的形象

数字人口播的人像可以存成账号里的「形象」，换一个会话也能直接复用。

- `beatra.avatars.list`：只读，不计费。返回形象列表（默认的在前）和 `default_avatar_id`。每个形象带 `image.artifact_id` 和搭配的 `voice`。把 `image.artifact_id` 作为 `beatra.videos.animate` 的人像传入，照常先对照实时模型卡检查这张图。
- `beatra.avatars.save`：不计费。用户同意保存，并确认了肖像授权之后才调用。`consent_subject` 是 `self`（照片里是用户本人）或 `authorized_other`（已取得本人的单独同意）。同一张图再保存一次，返回同一个形象。

```json
{
  "artifact_id": "artifact_01JX...",
  "display_name": "鹏博士·讲课",
  "purpose": "课程讲师",
  "voice_id": "voice_01JX...",
  "consent_attested": true,
  "consent_subject": "self"
}
```

## 任务状态与恢复

任务处于 `queued` 或 `running` 时持续轮询同一 `task_id`。创建响应丢失时，
只能用相同参数和同一 `client_request_id` 重试；图片、音频、提示词、模型
或输出控制有任何变化，都必须使用新 ID。

## 通过 REST 调用

直接协议集成可使用 `POST /v1/videos/image-to-video`，并遵循
[API 操作定义](https://docs.beatra.ai/zh/docs/api-reference/operations/videos/videos_i2v_v1_videos_image_to_video_post)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。