技能介绍

问题

调用 Sapiens AI 的 Agnes Video v2.0 时，常见难点不在写 prompt，而在异步任务流和参数约束。接口不会同步返回视频文件，而是先创建任务，再根据 task_id 轮询状态，最后从 remixed_from_video_id 字段中取视频 URL。如果把生成逻辑写死成“请求即得到结果”，很容易在排队、生成中和失败状态上卡住。

工作方式

该技能围绕 agnes-video-v2.0 封装两条核心端点：POST /v1/videos 创建任务，GET /v1/videos/{task_id} 查询进度。它支持四类工作流：

文本生成视频：由 prompt 描述场景，适合从文字直接生成短片
图像转视频：通过 image 输入静态图，让画面产生运动
多图过渡：使用 extra_body.image 在多个图像之间做镜头切换
关键帧动画：设置 extra_body.mode 为 keyframes，用于更明确的帧级控制

关键参数包括 height、width、frame_rate、seed、negative_prompt 和 num_frames。其中 num_frames 需要满足 8n+1 且不超过 441，并与 frame_rate 共同决定视频时长；降低 frame_rate 可以拉长时间，但会改变运动节奏。

适用边界

适合工程师在脚本、CLI 工具或自动化流程中集成视频生成任务。需要注意任务状态包括 queued、in_progress、completed 和 failed，完成时读取 remixed_from_video_id，失败时检查 error 字段。鉴权依赖 API Key，免费额度和参数上限也要纳入重试与监控设计。