让图片动起来

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

Agent 主路径

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

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

工具参数

{
  "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（已取得本人的单独同意）。同一张图再保存一次，返回同一个形象。

{
  "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 操作定义。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。

本页内容