让图片动起来

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 或其他编程助手。

工具参数

{
  "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 动画化图片。提示词必填，输出固定为 2K，时长为 4–15 秒，宽高比由输入图片派生。H3 支持 watermark，但不接受驱动音频或其他可选控制项。输入图片免费，生成视频按每秒 590 credits 计费。

任务状态与恢复

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

通过 REST 调用

直接协议集成可使用 POST /v1/videos/image-to-video，并遵循 API 操作定义。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。