教程
PixVerse V6 图生视频 API：可直接运行的 curl 与 Python 示例
- 模型
- pixverse-v6
在 hiapi 上使用 pixverse-v6/image-to-video 为静态图片制作动画，只需一次 POST /v1/tasks 调用加一次轮询——这与平台上所有生成模型使用的异步任务模式完全一致。它与文生视频端点的区别在于输入：你需要提供一个起始帧（image_url）以及一段描述它应如何运动的提示词。本指南给出可直接复制粘贴的 curl 和 Python 示例、该端点实际会校验的输入字段，以及一个会让从文生视频转来的人踩坑的意外之处。
你需要准备什么
- 一个 hiapi API 密钥。在控制台中创建，并通过
Authorization: Bearer sk-<your-key>发送。头部格式参见认证文档。 - 模型 ID 为
pixverse-v6/image-to-video（保留斜杠——它是 ID 的一部分，不是 URL 路径）。这与pixverse-v6/text-to-video是不同的模型 ID。 - 一个可公开访问的图片 URL 作为第一帧。平台会在服务端抓取该图片，因此
localhost或私有存储桶的链接无法使用——请把首帧托管在 API 可通过 GET 访问的位置。 - 使用 curl 无需安装任何东西。对于 Python 示例，只需要标准库加上
requests。
PixVerse V6 图生视频会把你提供的静态图作为起始帧，并将其动画化为 1–15 秒的片段。它通过统一的异步任务 API 运行——你提交任务、轮询结果，然后在输出 URL 过期前下载它。
最小可用请求（curl）
将任务提交到 POST /v1/tasks。image_url 和 prompt 均为必填：
curl -s -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer sk-<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6/image-to-video",
"input": {
"image_url": "https://cdn.example.com/your-first-frame.jpg",
"prompt": "Slow push-in; the subject turns toward the camera and smiles, soft breeze in the hair",
"duration": 5,
"resolution": "720p"
}
}'
响应会返回一个任务 ID：
{ "code": 200, "data": { "taskId": "a1b2c3d4-...." } }
然后轮询 GET /v1/tasks/<taskId>，直到 data.status 为 success：
curl -s https://api.hiapi.ai/v1/tasks/a1b2c3d4-.... \
-H "Authorization: Bearer sk-<your-key>"
成功时，完成的视频 URL 位于 data.output[0].url：
{
"code": 200,
"data": {
"status": "success",
"output": [{ "url": "https://temp.hiapi.ai/....mp4", "expireAt": 1760000000 }]
}
}
该输出 URL 是临时的——它带有 expireAt 时间戳。请立即下载 .mp4 并保存到你自己的存储桶；不要直接热链引用它。
Python 中的相同流程
import time, requests
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>", "Content-Type": "application/json"}
def create_task():
payload = {
"model": "pixverse-v6/image-to-video",
"input": {
"image_url": "https://cdn.example.com/your-first-frame.jpg",
"prompt": "Slow push-in; the subject turns toward the camera and smiles",
"duration": 5,
"resolution": "720p",
},
}
r = requests.post(BASE, json=payload, headers=HEADERS, timeout=60)
r.raise_for_status()
data = r.json()
task_id = (data.get("data") or {}).get("taskId")
if not task_id:
raise RuntimeError(f"create failed: {data}") # 400s echo the exact bad field
return task_id
def wait_for(task_id, timeout_s=600):
deadline = time.time() + timeout_s
while time.time() < deadline:
try:
r = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
task = (r.json().get("data") or {})
except requests.RequestException:
time.sleep(5) # one transient network blip should not abort the whole poll
continue
status = task.get("status")
if status == "success":
return task["output"][0]["url"]
if status == "fail":
raise RuntimeError(f"task failed: {task.get('error')}")
time.sleep(5) # still pending — keep the SAME task_id, re-poll
raise TimeoutError(task_id)
task_id = create_task()
url = wait_for(task_id)
video = requests.get(url, timeout=120).content
open("out.mp4", "wb").write(video)
print("saved out.mp4")
轮询循环会显式检查 success 和 fail，对其他任何状态都继续等待，因此无论任务在渲染过程中报告什么中间状态标签，它都能稳健处理。如果某次轮询请求出错，请休眠后重新轮询同一个保存的 task_id，而不要重新提交——重新提交会产生第二次渲染费用。
pixverse-v6/image-to-video 实际校验的参数
以下是线上端点实际接受的字段。我通过发送无效值并读取校验错误逐一确认，随后与模型文档进行了交叉核对：
| 字段 | 类型 | 取值 / 范围 | 说明 |
|---|---|---|---|
image_url |
string | 一个公开图片 URL | 必填。第一帧。单个 URL 字符串——不是数组。 |
prompt |
string | — | 必填。描述施加于该帧的运动。 |
duration |
integer | 1–15，默认 5 |
单位秒。必须是整数，不能是字符串。 |
resolution |
string | 360p、540p、720p、1080p |
输出分辨率。 |
negative_prompt |
string | — | 可选；需要规避的内容。 |
seed |
integer | — | 可选；复用以获得可复现结果。 |
style |
string | anime、3d_animation、clay、comic、cyberpunk |
可选预设风格。 |
generate_audio |
boolean | true / false，默认 false |
可选；开关生成的音轨/环境音。 |
这里没有 aspect_ratio 字段。这是与你可能见过的文生视频请求之间唯一真正的差异，值得牢记（见下文）。
生产注意事项
- 没有
aspect_ratio——输出几何形状跟随你的输入图片。文生视频端点接受一个aspect_ratio枚举；而这个端点会拒绝它。因为你提供了第一帧，片段会继承该帧的尺寸。如果你需要 9:16 竖屏片段，请在提交之前将image_url裁剪或填充为 9:16——没有比例旋钮可以覆盖它。 - 请求结构是封闭的。上表之外的任何字段都会被拒绝，报错为
invalid input: <root>: additional properties '<field>' not allowed。拼写错误或猜测的字段会在提交时大声失败，而不是被静默忽略。first_frame、image、input_image、motion_mode和camera_movement等字段都会被拒绝——起始图片放在image_url中，镜头运动写在prompt文本里。 duration是整数，不同于平台上某些接受字符串（"6"）的其他视频模型。发送"5"会返回invalid input: duration: got string, want integer。超出范围的值会直接报告边界，例如duration: maximum: got 999, want 15。- 错误一次返回一个字段，采用扁平信封格式：
{"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: image_url: missing required field \"image_url\""}。修复报告的字段并重新提交；下一个无效字段（如果有）会在下一次调用时浮现。 - 任务失败仍返回 HTTP 200。失败信息位于响应体中，形式为
data.status: "fail"——请检查状态字段，而不只是 HTTP 状态码。平台无法抓取的图片 URL 是常见原因，所以请先确认你的首帧是公开的。 - 按秒计费，并随分辨率和时长增长，因此 1080p/15s 片段比 540p/3s 片段贵得多。批量生成前请查看价格页面上的当前费率。
我验证了什么（以及没验证什么）
我通过向 pixverse-v6/image-to-video 的线上 /v1/tasks 端点发送刻意构造的无效值，并读取 API 自身的校验响应，梳理出了输入契约——这是一次只读的 schema 探测，未挂回调，也未产生渲染费用。值得记住的具体发现：
image_url是必填的第一帧字段，且是单个字符串，不是数组。发送数字会返回image_url: got number, want string；省略它会返回missing required field "image_url"。可以猜到的替代字段（first_frame、image、input_image）都会作为未知属性被拒绝。- 此端点拒绝
aspect_ratio（additional properties 'aspect_ratio' not allowed），尽管它在pixverse-v6/text-to-video上是有效的。这就是图生视频请求看起来与文生视频不同的具体原因：输出形状由你的帧决定，而不是由参数决定。 generate_audio是真正的布尔开关（默认false）——发送字符串会返回generate_audio: got string, want boolean。如果你想要声音，将其设为true；它不会被强制开启或关闭。
我在这次探测中并未渲染片段，因此本指南不声称运动质量或模型忠实保留输入帧的程度——它只记录该端点强制执行的精确请求契约。
相关内容
- PixVerse V6 图生视频——模型页面
- PixVerse V6 图生视频——API 文档
- 创建任务与获取任务详情参考
- 认证
- 价格
- hiapi 上的其他图生视频教程：hailuo-2.3 和 Grok Imagine 1.5
常见问题
为什么图生视频没有 aspect_ratio？因为片段以你的 image_url 帧开场并继承其尺寸。要控制输出比例，请在提交前调整输入图片大小或裁剪——该端点会将 aspect_ratio 作为未知字段拒绝。
image_url 接受多张图片吗？不接受。在此端点上它是单个 URL 字符串；传入数组会导致校验失败。它只设定起始帧。
duration 的单位是秒还是帧？秒——1 到 15 的任意整数，默认 5。必须是整数；字符串 "5" 会被拒绝。
这与文生视频端点有何不同？pixverse-v6/image-to-video 会为你提供的帧制作动画（image_url + prompt，无 aspect_ratio）。pixverse-v6/text-to-video 是单独的模型 ID，仅从提示词生成，并且确实接受 aspect_ratio。当你已经有想要让其运动的确切开场静帧时，请使用图生视频。
为什么我的请求失败并报“additional properties not allowed”？你发送了 schema 中不存在的字段。输入仅接受 image_url、prompt、duration、resolution、negative_prompt、seed、style 和 generate_audio。
