博客

教程

如何通过 HiAPI API 使用 kling-4.0-flash 图生视频:curl 与 Python

实用请求演练:首帧图像输入、异步任务轮询、同步音频与错误排查

2026年11月12日
封面图:一叠错位排列的米白纸张,边缘描炭黑,其中夹着一张锈红衬页,下方投下一道平整阴影。
模型
kling-4.0-flash
本页内容

kling-4.0-flash 图生视频端点的作用

kling-4.0-flash/image-to-video 是一个以图像为条件的视频生成模型。你给它一张图像——即首帧——外加一段文本提示词,它便返回一段生成的视频,该视频从这一帧开始,并按照你的描述演化。

写代码前最需要内化的一点:这不是一个在同一次 HTTP 交换中返回视频字节的请求/响应式调用。生成需要时间,因此该端点遵循异步任务模型。你的第一个请求提交一个任务;随后你通过轮询任务状态来获取结果,直到任务进入终止状态。

请把这三种概念在脑中区分开,因为它们对应客户端的三个不同部分:

  • 提交——你发送的载荷:首帧图像、提示词和生成选项。
  • 任务引用——提交时返回的标识符,用于之后查询该任务。
  • 结果获取——反复检查状态,最终返回完成的视频(或失败)。

一旦你把端点当作任务队列而非 RPC,集成的其余部分——轮询间隔、超时、重试——就变成了普通的异步管线,而不再是特殊情况。如果你希望在本演练之外同时参考更完整的端点文档,请把它在另一个标签页中打开,边看边操作。

发送请求之前

首次调用前需要准备好三件事。

1. API 凭证

你需要一个 HiAPI API 密钥。每个请求都要通过 Authorization 头以 bearer 令牌形式发送它。请勿将其纳入源代码管理——从环境变量读取,而不是粘贴到脚本中。

export HIAPI_API_KEY="your-api-key-here"

2. 端点路径

所有调用都通过统一的 HiAPI 接口进行。你针对的模型标识符是 kling-4.0-flash/image-to-video。你的提交请求和后续的状态查询都指向同一个模型命名空间,因此请把该标识符放在代码中的一个常量里,而不是到处散落字符串字面量。

3. 准备好的首帧图像

你需要一张图像作为开场帧。发送前,先确定两件事:

  • 如何传递它——作为可公开访问的 URL,还是作为编码后的图像数据,取决于该端点在你的使用场景下接受哪种形式。
  • 它是否格式良好——格式正确、可读,且不至于大到让请求体变得臃肿。

一条实用规则:保持请求体小而明确。如果传递 URL,请确保调用方无需认证即可访问它。如果传递编码数据,请确认编码恰好是端点所期望的。

同时准备一段简短、具体的提示词。当图生视频提示词描述的是运动与变化(什么在动、镜头如何运动),而不是复述帧中已经可见的内容时,效果最好。

可用的 curl 请求

下面是一个完整的提交调用。请将占位符替换为你自己的密钥、图像和提示词。

curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Slow dolly-in on the subject as light shifts across the scene",
    "image": "https://your-host.example/first-frame.jpg"
  }'

逐项说明:

  • -X POST——提交是写操作,不是查询。
  • URL——模型标识符是统一端点路径的一部分。这是你唯一指定模型的地方。
  • Authorization: Bearer $HIAPI_API_KEY——由 shell 从你的环境变量展开的头。用双引号包裹可以让变量展开,同时保持其值为单个参数。
  • Content-Type: application/json——请求体是 JSON;没有这个头,某些网关会拒绝或错误解析载荷。
  • -d '{ ... }'——JSON 请求体。prompt 描述运动;image 提供首帧。每个字段都是显式的——没有任何内容依赖位置或你看不到的默认值来隐含。

成功提交会返回一个包含任务标识符的 JSON 体。请捕获它——该值就是你操作该任务的句柄。如果你在交互式探索,可以把响应通过 JSON 格式化工具处理,以便复制标识符:

curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool

不要以为视频就在这个响应里。它不在——这个响应只告诉你任务已被接受。

同样的请求用 Python 实现

Python 客户端完全对应 curl 载荷。切换语言不会改变语义,只是发送字节的机制不同。使用 requests 并从环境变量读取密钥:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"

def submit_job(prompt: str, image: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/{MODEL}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "image": image,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

job = submit_job(
    prompt="Slow dolly-in on the subject as light shifts across the scene",
    image="https://your-host.example/first-frame.jpg",
)
print(job)

移植要点:

  • 用 json= 替代 -d——传入 dict 让 requests 序列化请求体并设置内容类型。你得到与 curl 示例相同的线上格式,而无需手写 JSON。
  • raise_for_status()——将非 2xx 响应转换为异常,以免你误将错误体当作任务引用。
  • timeout=30——提交应该很快。较宽裕的超时可以防止连接挂起,同时不会掩盖真正缓慢的调用。
  • 模型使用单个常量——如果以后切换模型,只需改一行。

返回的 dict 包含任务标识符,下一节将加以利用。

处理异步任务生命周期

集成模式是先提交,再轮询。两个阶段,界限分明。

阶段 1:提交并捕获引用

上一节中的 submit_job 调用会返回一个包含任务标识符的 JSON 体。请保存它。后续每次状态检查都需要它,丢失它意味着丢失该任务。

阶段 2:轮询直到终止

状态检查是对同一任务的读请求。按固定间隔重复,直到任务达到终止状态——完成或失败。一个带尝试次数上限的简单循环:

import time

def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/{MODEL}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()

        state = status.get("status")
        if state in ("succeeded", "failed"):
            return status
        time.sleep(interval)

    raise TimeoutError(f"Job {task_id} did not finish in time")

值得刻意做出的设计决策:

  • 限制循环次数。永远不要无限轮询。最大尝试次数加固定间隔可给出可预测的最坏等待时间。
  • 在检查之间休眠,而不是在请求内部休眠。过度频繁的轮询浪费配额,还可能触发速率限制。
  • 把失败视为终止状态。失败的任务不会在下一次轮询中变成成功——停止并暴露错误。
  • 区分等待中与已完成。只有终止状态才结束循环;其他任何状态都意味着继续等待。
  • 持久化任务 ID。如果进程在轮询中途崩溃,你希望能恢复而不是重新生成。

生产环境中,应将轮询移出请求线程——交给后台工作器或队列消费者——这样长时间生成不会让 Web 请求一直保持打开。

使用同步音频选项

该端点提供同步音频选项。实践中,这对客户端意味着一件事:如果启用它,调用将阻塞直到生成完成,而不是返回一个供你轮询的任务引用。

这会以具体方式改变你的设计:

  • 超时预算必须增大。阻塞式生成调用可能比典型 API 请求耗时得多。将客户端超时设置为覆盖整个预期时长,而不是提交时长。
  • 中途无法检查点。使用轮询时,你可以崩溃后用任务 ID 恢复。使用阻塞调用时,连接断开就意味着重做工作。
  • 线程和连接池压力。阻塞调用会在整个持续时间内占用一个工作器。在 Web 服务器中,这会迅速限制你的并发能力。

何时可以接受阻塞调用?当你运行一次性脚本、CLI 工具或批处理任务,没有其他东西在等待结果,且简单性胜过吞吐量时。在这些场景下,同步调用完全移除了轮询机制,代码也更短。

何时应避免?在任何面向用户的请求路径中、在高并发服务中,或在客户端可能超时并重试的任何地方——重试的阻塞调用可能让你的工作量翻倍。在这些场景中,请保留上一节的异步提交并轮询模式,关闭同步选项。

排查常见失败

按层次处理失败。你看到的第一个错误通常是最浅层的,因此修复它并重新运行,而不是一次猜测多个问题。

认证错误

401 或 403 意味着凭证缺失、格式错误或被拒绝。检查 HIAPI_API_KEY 是否确实在你进程所看到的环境中设置——在一个 shell 中导出的变量不会传递到另一个 shell 或容器。确认 Authorization 头是 Bearer <key>,只有一个空格,没有从复制粘贴带来的多余引号。

载荷格式错误

400 通常意味着请求体无法解析或缺少必填字段。重新检查你是否发送了 Content-Type: application/json、JSON 是否有效(尾随逗号会导致失败),以及 prompt 和 image 是否都存在且为非空字符串。调试时,请转储你实际发送的请求体——而不是你打算发送的 dict。

图像输入问题

这些问题通常表现为验证错误,而不是明显的图像错误。请按顺序检查:

  • 可达性——如果传递的是 URL,请从请求发起的同一网络环境获取它。在浏览器中可用的 URL 对 API 而言可能被防火墙拦截或受认证保护。
  • 格式——确认图像是受支持的、未损坏的文件。如有疑问,重新导出。
  • 大小——过大的图像可能导致验证失败,或使请求体膨胀超出限制。
  • 编码——如果发送编码数据,请完全确认编码与端点期望的一致;不匹配的前缀或多余空白都会导致失败。

任务级失败

如果提交成功但任务以失败状态结束,说明请求格式良好但生成未完成。重新阅读提示词,检查是否有歧义或物理上不合理运动,并确认首帧图像确实可用作起点。用简化后的提示词重试一次,再假定存在系统性问题——并记录任务 ID 与失败信息,以便日后关联。

轮询循环超时

wait_for_job 抛出的 TimeoutError 意味着你的限制太紧,而不是任务已死。增大尝试次数或间隔,并检查你是否在轮询一个更早、已结束运行的 task ID。

从最小请求开始——一张图像、一段简短提示词、无可选字段——只有基线可用后才增加复杂度。当载荷小而明确时,大多数集成问题都会消失。

立即开始构建持久 AI 产物

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

阅读 API 文档