教程

如何通过 hiapi API 使用 veo-3.1-lite/image-to-video

2026年11月3日

模型: veo-3.1-lite

Veo 3.1 Lite 能把单张参考图加上一段文本提示词变成一段短视频，而在 hiapi 上，它通过平台上所有模型共用的同一套异步任务 API 对外提供。本指南会走一遍真实可用的请求流程：获取密钥、调用 POST /v1/tasks、取回结果，以及当你把这套流程从一次性脚本推进到生产环境时需要关注的细节（回调、幂等性、错误处理）。

你要构建什么，以及先准备什么

你会把一个图片 URL 和一段提示词发送给 veo-3.1-lite/image-to-video 模型，拿回一个托管在外的 .mp4 URL。一切都通过 hiapi 的统一任务端点运行，所以同样的请求结构对平台上每个视频和图像模型都适用——只有 model id 和 input 字段会变。

开始之前：

创建一个 hiapi 账户，并从控制台获取一个 API 密钥。密钥形如 sk-...。
准备一个公网可访问的图片 URL——API 会在服务端抓取它，所以 localhost 路径或私有桶都行不通。
在运行真实（非测试）请求之前，先到定价页查看 veo-3.1-lite/image-to-video 的当前价格，因为费用取决于时长和分辨率。

没有免费层或无密钥模式——每次调用都需要 Authorization: Bearer sk-<your-key>。

最小可用示例

hiapi 的任务 API 就是两次调用：创建任务，然后要么轮询它，要么让回调告诉你任务何时完成。下面是轮询版本的 Python 代码，只用到 requests 和 time：

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

如果你只想看看线上传输格式，下面是同样事情的原始 curl 写法：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

关于 input 模式里有几点值得特别知道，因为它比那种“随便传什么”的通用端点更严格——多余字段会被直接拒绝，而不是被静默忽略：

prompt 和 image_url 是仅有的两个必填字段。image_url 是单数——这个模型只接受恰好一张参考图，不是数组。
duration 只接受 4、6 或 8（秒）——不接受其他整数。
aspect_ratio 接受 auto、16:9 或 9:16。
resolution 接受 720p 或 1080p。
可选附加项：seed（整数，用于复现）、generate_audio（布尔值）、negative_prompt（字符串）。

注意模型 id 是裸 id，即 veo-3.1-lite/image-to-video——不要额外给它加前缀或命名空间。

一旦 status 变为 "success"，输出视频位于 data.output[0].url。该 URL 是临时的（带有 expireAt），所以请立即下载或重新托管，而不是保存这个热链接。

生产环境注意事项：回调、幂等性与错误

每 5 秒轮询一次对脚本来说没问题，但在同时处理许多任务的服务器里就很浪费。对于生产流量，更推荐使用回调：在同一个创建任务请求里传入一个 callback 对象，hiapi 就会把最终结果 POST 到你的端点，而不是由你去询问。

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

这里关键设置是 when: "final"——表示任务到达终态（success 或 fail）时只通知你一次，而不是每次中间状态变化都通知。你的 webhook 处理器应验证任务 id，然后查回你最初调用 POST /v1/tasks 时创建的本地任务记录。

幂等性。 如果你的服务可能重试创建任务调用（超时、至少一次投递等），就附加一个 Idempotency-Key 头，最长 255 字节：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

在同一账户下用相同密钥重试，会返回原始 taskId，而不是创建第二个（可计费的）任务——可以放心从重试循环中发起，而不会向客户重复收费。

轮询 vs. 回调，简而言之： 对于脚本、notebook 或低流量的内部工具，如果你本来就在阻塞等待结果，用轮询。对于任何服务端且并发的场景，用回调——它避免保持连接打开，并能扩展到大量进行中的任务，而无需为每个任务跑轮询循环。

错误处理。 错误或已撤销的密钥会返回 HTTP 401 和 error.code: "permission_denied"——要专门检查这一点，而不是假定任何非 2xx 都意味着视频生成本身失败。格式错误的 input（缺少 prompt、duration 超出枚举范围、无法识别的字段）会返回 HTTP 400 和 error_code: "INVALID_REQUEST"，并附带指明具体问题字段的消息——值得直接展现在你自己的日志里，而不是吞掉，因为消息会告诉你到底该修什么。任务一旦被接受，生成侧失败会以轮询/回调载荷上的 status: "fail" 和 error 对象体现——只有消息表明是上游瞬时问题时才把它当作可重试，而不是模式问题。

常见问题

我需要把 image_url 作为 data URI 或 base64 传入吗？ 不需要——image_url 必须是 hiapi 服务器能抓取的公网 HTTP(S) URL。此模型不接受 base64 编码的图片。

我可以不用参考图生成视频吗？ 用 veo-3.1-lite/image-to-video 不行——它是图生视频模型，image_url 是必填的。如果你想要纯文本生成，请改用文生视频模型；非 lite 的 Veo 3.1 模型页列出了其可用模式。

为什么我传了所有必填字段，请求还是 400？ 检查是否有额外字段——此模型的输入模式会拒绝任何不在允许列表中的内容（prompt、image_url、duration、aspect_ratio、resolution、seed、generate_audio、negative_prompt）。错误消息会指明它不认识的确切字段。

生成实际需要多长时间？ 它会随持续时长和当前队列深度变化，这正是为什么用短间隔轮询或回调是正确做法，而不是假定一个固定等待时间。

输出里能有音频吗？ 可以，通过 generate_audio 布尔值——查看模型文档了解当前默认值以及它如何影响费用。

如果任务完成时我的回调端点宕机了会怎样？ 不要只依赖回调到达——保留创建调用返回的 taskId，如果在合理时间窗口内没收到回调，就回退到 GET /v1/tasks/<id> 轮询。