AI 视频中的首帧与尾帧控制：hiapi 上跨模型精确运动指南

大多数图生视频 API 只接收一张静态图，然后即兴生成运动。只有少数模型允许你锁定镜头的终点，而不只是起点——你提供首帧和尾帧，模型在两者之间插值生成运动。这正是“让这张照片动起来”和“精确实现这一转场”之间的差别。

问题在于：各模型对尾帧控制的支持并不一致，即便在同一厂商的产品线内，旗舰档与快速/极速档也可能不同。本教程会明确说明哪些 hiapi 视频模型仅支持首帧控制、哪些支持首帧+尾帧控制，并给出各自真实（且并不统一）的输入字段，这样你就不会在经过一番折腾后才发现所选模型悄悄忽略了你的尾帧。

1. 你需要准备什么

一个来自控制台的 hiapi API key（sk-...），以及两张目标模型可以抓取的图片 URL（公网 HTTPS URL——任务端点不支持本地上传文件）。以下每个模型都通过同一个统一的 task API 调用，因此只要你的 key 能用于其中一个模型，就能用于所有模型。

2. 最小可运行示例

所有 hiapi 视频生成都走同一个端点：创建任务，然后轮询它（或使用回调——见生产模式）直到进入终态。

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video 是这一模式最典型的例子：input.image_urls 接收一个或两个图片 URL。传一个，模型只锚定首帧，其余部分自由发挥；传两个，第二个 URL 就成为强制尾帧——模型会被告知镜头必须落在哪里。时长是 3–15（秒）的整数，resolution 为 720p / 1080p / 4k，可选的 sound 布尔值会添加生成的氛围音频。这里没有 aspect_ratio 字段——输出画幅跟随你提供的帧。

并非所有模型都是这种结构。seedance-2.5/image-to-video 通过两个分开命名的字段而不是数组实现同样的效果：

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url 只有在与 first_frame_url 配对时才有意义——你可以只发送 first_frame_url 做仅首帧的镜头，但不能反过来。该模型时长范围为 4–30s，分辨率最高仅 720p/1080p（没有 4K 档），且 aspect_ratio 默认为 adaptive，即跟随首帧，而不是取显式的 16:9/9:16 值。

各模型的字段名确实不同——image_urls 与 first_frame_url/last_frame_url——因此每次换模型都应视为一次 schema 变更，而不是可直接替换。

并非每个模型都支持

veo-3.1/image-to-video 接收单个 image_url 字符串，完全没有尾帧参数——你可以设置 aspect_ratio（auto/16:9/9:16）、resolution，以及固定的 duration 枚举（4、6 或 8 秒），但无法锁定结束帧。Kling 产品线低一档也是同样情况：kling-3.0-turbo/image-to-video（kling-3.0-omni 的快速/廉价版本）的 image_urls 最多只接受一项——没有尾帧，也没有 4K 分辨率。如果你需要尾帧控制，应选择旗舰档或专为此构建的模型（如 seedance-2.5），而不是根据模型家族名称想当然。

3. 生产模式

规模化场景下用回调代替轮询。 在同一个请求体中传入 callback 对象，而不是在循环中轮询：

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" 只触发一次，在任务达到任一终态时触发——succeeded 或 failed 都是终态，因此你的 webhook 处理器应按 taskId 去重，而不是假设回调只代表成功。轮询 GET /v1/tasks/:id 更适合本地调试、低频一次性调用，或作为回调始终未到达时（网络抖动、你的端点短暂下线）的对账兜底。

幂等性。 超时或连接中断后的重试如果不小心，可能创建重复任务——记录创建调用返回的任务 id，在考虑提交新任务之前，先对该 id 执行 GET 作为重试。

输出 URL 会过期。 每个输出条目上的 expireAt 字段并非装饰——无论你是通过回调还是轮询获知任务成功，都应尽快下载视频并持久化（保存到你自己的存储）。

认证失败。 错误或缺失的 key 会返回 HTTP 401 及 {"error": {"code": "permission_denied", ...}}。应显式检查该状态/错误码，而不是假设任何非 2xx 都意味着生成本身失败——在错误处理中区分“我的 key 错了”和“模型拒绝了我的输入”很有价值，因为修复方式完全不同。

4. 相关页面

• Kling 3.0 Omni 图生视频模型页 —— 上述示例所用模型的定价、在线体验和完整参数参考。
• Seedance 2.5 图生视频模型页 —— first_frame_url/last_frame_url 变体。
• 认证文档 —— Authorization: Bearer sk-... 请求头与 key 作用域如何工作。
• 创建任务文档 —— 完整的 /v1/tasks 请求/响应参考，包括回调选项。
• hiapi 定价 —— 当前按秒和按分辨率的价格（计费因模型和分辨率而异，请查看实时页面而非写死的数字）。

5. 常见问题

哪些 hiapi 视频模型支持尾帧控制？ kling-3.0-omni/image-to-video（通过含 2 项的 image_urls 数组）和 seedance-2.5/image-to-video（通过 first_frame_url + last_frame_url）目前都支持。veo-3.1/image-to-video 和 kling-3.0-turbo/image-to-video 不支持——它们只接受单张起始帧。

可以只指定尾帧而不提供 prompt 吗？ 两个模型仍接受（通常也期望）在帧之外提供 prompt——它引导两帧之间的运动，而不仅仅是内容。并非每个模型都会直接拒绝空或缺失的 prompt，但显式描述转场会让运动更可预测。

两帧需要相同宽高比吗？ kling-3.0-omni/image-to-video 和 seedance-2.5/image-to-video 都没有提供独立于图片设置的显式 aspect_ratio——输出画幅跟随输入帧，因此首帧和尾帧宽高比不一致会产生明显别扭的结果，而不是报错。提交前请将两帧裁剪或补边到相同比例。

如果只发送尾帧而不发送首帧会怎样？ 两个模型都不支持——在 seedance-2.5 上，last_frame_url 只能与 first_frame_url 一起使用；kling-3.0-omni 的数组是按位置读取的（第一项 = 首帧）。不存在只指定结束帧的“反向”模式。

尾帧控制等同于视频到视频的运动迁移吗？ 不等同——那是另一项能力（hiapi 上的 seedance-2.5/reference-to-video，它接收参考视频来驱动运动或镜头运动，而不是两张静态图）。首/尾帧控制在两张图片之间插值；参考视频到视频则模仿已有片段的运动模式。

添加尾帧比仅首帧生成更贵吗？ 两个模型都按秒/按分辨率计费，而非按输入图片计费，因此添加尾帧本身不会增加成本——请查看定价页面获取当前费率。