博客

教程

如何通过 HiAPI API 使用 pixverse-v6-max 图生视频:curl、Python 与一条可用的请求

2026年11月13日
扁平编辑风格封面图:深松绿底色上,大型棱镜被切成鼠尾草绿与雾绿色的色块。
本页内容

pixverse-v6-max 图生视频端点要求什么

HiAPI 上的 pixverse-v6-max/image-to-video 端点是一个异步的、以图像为条件的视频生成任务。这一句话几乎决定了你在集成它时所做的每一个决定。

该端点接收一张源图像(首帧)以及一组生成参数,返回的是一个任务引用,而不是成片视频。实际渲染在服务端进行,根据你选择的参数,可能需要几秒到几分钟不等。你的客户端负责提交任务,然后不断查询其状态,直到它报告一个终态。

将此与同步图像编辑对比:在同步编辑中,你 POST 一个请求体,然后就在同一个 HTTP 响应里拿到转换后的图像。而这里的流程是:

  1. 将你的图像和参数 POST 到生成端点。
  2. 收到一个任务标识符(通常还带有初始状态)。
  3. 按间隔 GET 任务状态,直到它完成或失败。
  4. 从已完成的任务响应体中读取生成的视频 URL。

由于这种分离,存在两类不同的错误:提交阶段的问题(认证错误、请求体格式错误、图像被拒)和执行阶段的问题(任务被接受后失败或停滞)。良好的集成会显式处理这两类问题——具体检查清单见后面的故障排查部分。

还有一点需要牢记:源图像是锚点。模型从这一首帧开始动画,因此图像质量、宽高比和内容对输出的影响,比你提供的任何提示词文本都要大。请把上传的正确性当作首要关注点,而不是事后才考虑的事情。

准备好你的 API 密钥和端点

在发出第一个请求之前,你只需要两样东西:一个 HiAPI API 密钥,以及该端点正确的基础 URL。

获取你的密钥

在你的 HiAPI 账户控制台中创建一个 API 密钥。像对待密码一样对待它:把它放在环境变量中,而不是源代码或 shell 历史记录里。

export HIAPI_API_KEY="your_key_here"

如果你在本地使用 .env 文件,请在提交任何内容之前先把它加入 .gitignore。任何出现在共享日志、截图或代码仓库中的密钥都应立即轮换。

了解你的基础 URL 和路径

该端点位于 HiAPI API 主机之下,模型路径为 pixverse-v6-max/image-to-video。在下面的示例中,基础 URL 显示为 https://api.hiapi.ai,完整路径由它拼接而成。如果你的账户或区域给你的主机不同,请一致地替换它——主机与密钥不匹配是导致 401 的最常见原因之一,而开发者常误以为这是“密钥无效”。

选择你的工具

  • curl 用于首次快速验证——它排除了请求本身之外的所有变量。
  • Python 3 配合 requests(或 httpx)用于实际集成。
python3 -c "import requests; print(requests.__version__)"

如果它打印出版本号,你就准备好了。本文中的示例不需要安装 SDK;一切都是纯 HTTP,这也意味着你之后可以将其移植到任何语言。一旦确认了密钥和主机,你就可以开始构建请求了。

使用 curl 构建请求

从能够真正成功的最小请求开始,然后再添加参数。下面的请求体展示了一个完整的图生视频提交的结构。

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://your-cdn.example.com/first-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

这里发生了三件事:

  • 认证是在 Authorization 头中携带的 bearer token。
  • 请求体是 JSON,因此图像以 URL 字符串形式提供(如何改为传递本地文件见下一节)。
  • 两个生成参数——duration 和 aspect_ratio——是顶层字段。

成功的提交会返回一个包含任务标识符的 JSON 对象。把它捕获下来:

JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"

然后轮询它:

curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

失败时一定要检查状态字段和原始错误响应体。curl 在退出码为 0 时仍可能打印错误 JSON,因此在脚本中不要只依赖退出码。

正确提供首帧图像

源图像是最常见的失败点,几乎每一次拒绝都归结为以下四种原因之一。

1. 图像不可访问

当你传递 URL 时,HiAPI 的服务器必须能够 GET 到它——从他们的网络访问,而不是你的网络。一个 localhost URL、私有存储桶、六十秒后过期的签名 URL,或位于 VPN 之后的端点都会失败。请使用公开可读的对象存储 URL 或 CDN 链接,并在一个不带 cookie 的全新浏览器会话中确认它能加载。

2. 图像格式不受支持

坚持使用标准网页格式——JPEG、PNG、WebP。扩展名不常见的文件、手机拍摄的 HEIC,或动态 GIF 都有风险。如果你的流水线产生了一些特殊格式,请先转码。

3. 首帧与声明的宽高比不匹配

这一点比较微妙。如果你的源图像是正方形,但你请求 16:9,服务就必须裁剪、填充或拒绝该输入。行为可能各不相同,而这三者都不是大多数开发者想要的。请在上传之前自己裁剪或加黑边,使图像几何形状已经与你将请求的 aspect_ratio 匹配。这能让输出可预测,并避免浪费一个任务。

4. 图像过大或过小

极高分辨率的静态图(例如 8K 相机输出)会消耗带宽,可能被拒绝或降采样;极小的缩略图则让模型几乎没有可动画的内容。请将图像归一化到合理的长边尺寸,作为上传前步骤的一部分。

传递本地文件

如果该端点对图像字段接受 multipart 上传,模式如下:

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -F "image=@./first-frame.jpg" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

注意,使用 multipart 时数值字段会变成字符串。请查阅端点参考文档了解接受哪些内容类型,并在生产流水线中优先使用 URL 形式——这样可以让大型二进制文件完全不出现在你的应用服务器上。

设置时长和宽高比

这两个字段对成本和输出的影响比请求体中的任何其他内容都大。

duration

duration 以秒为单位,表示生成片段的长度。它也是最直接关系到计费的字段——实时定价根据你请求的输出时长计算,因此请慎重选择,而不是默认取最大值。实用建议:

  • 从能讲清你故事的最短时长开始。5 秒片段非常适合循环播放、产品预告或社交钩子。
  • 仅在镜头确实需要更长时间时才使用更长时长;一个静态首帧长时间动画化后往往会漂移并失去连贯性。
  • 在客户端进行验证:在请求离开你的服务之前,拒绝非整数、零、负数和荒谬的大数值。
if not isinstance(duration, int) or not 1 <= duration <= 8:
    raise ValueError("duration out of supported range")

请在端点参考文档中确认当前支持的区间,并在你的验证逻辑中镜像它——不要硬编码本文中的假设。

aspect_ratio

aspect_ratio 是一个字符串,例如 "16:9"、"9:16" 或 "1:1"。它控制输出画面的几何形状。

  • 16:9 用于横屏:YouTube、网页主视觉视频、桌面播放。
  • 9:16 用于竖屏:Reels、Shorts、TikTok 风格的投放。
  • 1:1 用于信息流和缩略图。

两条规则可以让你避免麻烦。第一,让源图像与请求的比例匹配——在横屏请求中使用竖屏首帧会导致你很可能并不想要的裁剪。第二,把比例当作枚举,而不是自由文本:对照白名单进行验证,这样像 "16x9" 这样的拼写错误会在你的代码中快速失败,而不是在一次往返之后才失败。

其他一切

如果该端点暴露了额外的生成控制项,请把它们排除在你的第一个请求之外。一个最小的、已验证可用的请求体是你的基线;一次只添加一个参数,并对比输出。这种纪律能让哪个字段导致了回归变得一目了然。

用 Python 实现同样的请求

下面是把 curl 流程翻译成 Python 的版本。它刻意保持依赖精简:requests 加上标准库。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    resp = requests.post(
        f"{BASE}/v1/pixverse-v6-max/image-to-video",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def fetch(job_id: str) -> dict:
    resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job_id = submit("https://your-cdn.example.com/first-frame.jpg")
    print("submitted", job_id)

一些值得借鉴的刻意选择:

  • 提交时调用 raise_for_status()。 400 或 401 应立即以异常形式暴露,而不是在你尝试从错误响应体中读取 ["id"] 时变成 KeyError。
  • 显式超时。 没有超时,一个停滞的连接会让你的 worker 无限挂起。
  • 从环境读取配置。 基础 URL 和密钥从不在代码中写死。
  • 小而带类型的辅助函数。 submit 返回任务 id 字符串;fetch 返回字典。把解析集中在一处意味着模式变更只需改一行。

如果你更喜欢 httpx,替换为 httpx.post(...) 和 httpx.get(...) 即可;调用在其他方面完全相同。对于在 Web 请求处理器内运行的任何内容,请在此处提交,然后把任务 id 交给后台 worker,而不是让用户的 HTTP 请求阻塞在视频生成上。

轮询异步任务直到完成

轮询是大多数教程一带而过、也是大多数事故来源的部分。循环本身很短;围绕它的纪律才是关键。

def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = fetch(job_id)
        status = job.get("status")
        if status == "completed":
            return job["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish within {timeout}s")

上面编码的要点:

  • 始终设定截止时间。 视频生成很慢;无界循环会变成无界账单和卡死的 worker。对于短片,十分钟是合理的上限——根据你的时长设置调整它。
  • 区分终态。 只有 completed 会产生 URL。failed 和 cancelled 也是终态——停止轮询并暴露 error 字段。
  • 使用合理的间隔。 每隔几秒就足够了。猛刷状态端点会让你被限流,而且不会告诉你任何新信息。
  • 对长任务温和退避:在第一分钟后将间隔从 3 秒增长到 10 秒。这能减少负载,且不会给你增加任何延迟成本。
  • 持久化任务 id。 将它们与你自己的记录一起存储,这样如果进程重启,你可以恢复轮询,而不必重新提交——并重新付费——同一个任务。
  • 绝不要用你的 API 密钥直接从浏览器轮询。 通过你的后端代理状态检查。

当任务完成时,及时将视频下载到你自己的存储中,而不是永远链接到返回的 URL;生成的资产 URL 不保证永久有效。

排查失败和停滞的任务

按顺序执行此检查清单。每一步隔离一个层面。

提交错误(任务从未创建)

  • 401 Unauthorized —— 密钥缺失、格式错误、已被撤销,或与错误的主机配对。验证头部是否恰好为 Authorization: Bearer <key>,中间只有一个空格,且环境变量中没有多余换行。
  • 403 Forbidden —— 密钥有效,但不允许用于此模型或端点。逐字符检查资源路径:pixverse-v6-max/image-to-video。
  • 400 Bad Request —— 你的 JSON 格式错误或某个字段无效。解码错误响应体;它通常会指出有问题的字段。常见元凶:duration 是字符串而不是数字、"16x9" 而不是 "16:9"、缺少 image。
  • 422 类验证错误 —— 字段存在但超出范围。对照端点参考文档,而不是猜测。
  • 429 Too Many Requests —— 你提交得太快。将提交排队,并使用带抖动的指数退避重试;绝不要在紧密循环中重试。

执行失败(任务已创建但未成功)

  • 状态为 failed,并带有与图像相关的错误 —— 提交后对源 URL 的拉取失败。这是经典的“在我的浏览器里能行”陷阱:该 URL 需要 cookie、referrer 或 IP 白名单。请将图像公开重新托管。
  • 状态为 failed,并带有内容或验证错误 —— 源图像因技术原因(格式、几何形状、大小)被拒绝。请转码、调整大小,并重新裁剪到声明的宽高比。
  • 任务在你的截止时间之后仍卡在排队或处理状态 —— 首先确认你读取的是正确的任务 id(复制粘贴错误出奇地常见)。然后检查状态是否确实未变,或者你的轮询是否打到了错误的基础 URL。如果它确实停滞了,在 API 允许的情况下取消并重新提交一次;反复静默重新提交正是预算消失的方式。

一个节省时间的习惯

为每次调用记录完整的请求 id、任务 id、HTTP 状态和响应体——并对密钥进行脱敏。当凌晨两点出问题时,一个请求 id 就是五分钟修复与一小时猜测之间的区别。从最小的、已验证可用的请求体开始,一次添加一个参数,你几乎根本不需要这份检查清单。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档