博客

教程

如何通过 HiAPI API 调用 kling-3.0-omni/transformation:curl 与 Python 指南

在 HiAPI 上进行视频风格转换的可用请求完整演练

2026年11月12日
HiAPI 博客封面图:深靛蓝底上嵌套的宽箭头呈阶梯状递进,杏色前缘勾勒信号流示意。
本页内容

transformation 端点的功能与适用场景

kling-3.0-omni/transformation 是 HiAPI 上的视频风格转换端点。你向它提供两样东西:一个源视频和一段自然语言风格指令。它返回一个新视频,其中源视频的内容得以保留,但以所请求的视觉风格呈现。

可以把它看作一个隐藏在 HTTP 调用背后的后期制作步骤。你无需训练模型、维护 GPU 集群或管理检查点文件。你描述想要的视觉效果,指向一段视频,端点就会产出渲染结果。

该端点适用的场景

  • 为现有素材添加风格。你已经有了一段镜头,想让它呈现为动画、水彩、胶片颗粒、黏土动画或其他效果。内容与运动来自你的视频,端点改变的是表面质感。
  • 批量保持一致的风格。由于风格以指令形式表达,你可以在许多源视频上复用同一个提示词,获得一套风格连贯的成品。
  • 原型验证风格开发。创意团队可以在投入更重的制作流程之前,低成本地迭代风格方向。

不适用的场景

  • 你需要从零生成视频(文生视频是另一项任务)。
  • 你需要逐帧精确的编辑、剪辑或合成。转换只重塑风格,不做编辑。
  • 你的源素材只有音频或是一张静态图片。

本指南的其余部分将逐步讲解请求结构、可直接运行的 curl 调用、对应的 Python 版本,以及围绕 4K 输出和长时间任务的操作细节。

请求解析:源视频、风格指令与输出选项

一个转换请求并不复杂。在编写代码之前,将其拆分为三组字段:源视频、指令和输出设置。

源视频

端点需要能够访问你的输入。实践中,你传入一个平台可以抓取的 URL,或者 HiAPI 文件上传步骤返回的标识符。实用规则是:源文件必须能从服务端访问,而不是从你的笔记本电脑访问。localhost 路径或位于你 VPN 之后的文件都不可行。

源格式应保持保守——使用广泛支持的容器与编解码器。如果你的视频由特殊流程生成且未通过校验,先将其重新编码为标准 H.264 MP4。这一步就能解决很大一部分输入错误。

风格指令

这是对目标视觉效果的自然语言描述。它是请求中最具影响力的字段,也是最值得反复推敲的字段。

  • 描述视觉处理,而非内容。内容来自视频;告诉模型屏幕上已有的东西只会浪费提示词预算。
  • 对媒介和质感要具体:“带有可见指纹痕迹的定格黏土动画”比“动画”传达了更多信息。
  • 在重要时明确要保留什么:“保持面部可识别,镜头运动不变”。
  • 控制在一段有重点的文字内。冗长、自相矛盾的提示词往往会平均成平淡无奇的结果。

输出选项

输出设置控制分辨率和其它交付细节。主要决策是请求 4K 还是标准分辨率。更高分辨率消耗更多算力、耗时更长,因此应将其视为有意识的决策而非默认选项。该端点在一般情况下以异步任务运行,因此你的请求通常返回一个任务引用,你需要轮询或等待,而不是直接返回成品文件。

先把你的输入映射到这三组字段,实际的 JSON 请求体就会变得清晰明了。

从零开始的可用 curl 请求

确认理解最快的方式是一次最小化调用。下面的形式发送一个源视频 URL 和一段风格指令,并请求标准分辨率的结果。请将占位符值替换为你自己的值。

curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": "转换为手绘水彩动画,边缘柔和晕染,可见纸张纹理,采用温暖有限的调色板。保留面部和镜头运动。",
    "resolution": "1080p"
  }'

各部分的作用

  • URL 路径指定端点。必须完全准确;这里的拼写错误会返回路由错误,而不是校验错误。
  • Authorization 请求头携带你的 HiAPI 密钥。将其导出为环境变量,而不是粘贴进 shell 历史记录。
  • video_url 是源视频。必须能被服务端抓取。
  • prompt 是风格指令。这是你会修改最多的字段。
  • resolution 是输出设置。迭代时从低分辨率开始,等效果确定后再提高。

解读响应

成功的响应会给你一个任务对象。记录任务标识符和任何状态字段:

{
  "id": "job_abc123",
  "status": "queued"
}

确切的字段名应从实时响应中读取,而不是凭假设。重要习惯在任何语言中都一样:解析 JSON,提取任务 id,并将完成的视频视为稍后到达的东西。不要编写假设首次响应就包含可播放文件的代码。

同样的请求在 Python 中

Python 版本就是 curl 调用,把 JSON 请求体表达为字典。使用 requests 可保持可读性且依赖轻量。

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "video_url": "https://your-cdn.example.com/clips/source.mp4",
    "prompt": (
        "转换为手绘水彩动画,边缘柔和晕染,可见纸张纹理,"
        "采用温暖有限的调色板。保留面部和镜头运动。"
    ),
    "resolution": "1080p",
}

resp = requests.post(
    f"{BASE}/kling-3.0-omni/transformation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))

轮询直到任务完成

由于渲染是异步的,请将等待包装在一个循环中,设置有限的尝试次数和检查之间的休眠时间。休眠时间要足够宽裕,以免频繁请求 API,并设置总等待时间上限,以免卡住的任务挂起你的工作进程。

def wait_for_job(job_id, max_attempts=60, interval=10):
    for _ in range(max_attempts):
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error") or "job failed")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

result = wait_for_job(job_id)
print(result.get("output") or result)

使其具备生产环境安全性

  • 从 API 响应文档中读取端点路径和轮询路由,而不是硬编码可能发生漂移的假设。
  • 提交时记录任务 id。如果下游出现问题,这是你唯一的抓手。
  • 将 failed 和超时视为不同的结果。失败的任务通常是参数问题;超时通常是容量或时长问题。

处理 4K 输出与长时间运行的任务

两个变量主导该端点的操作行为:输出分辨率和输入时长。要明确为两者做好规划。

4K 输出

4K 是交付决策,不是默认值。每个输出像素都消耗算力,从标准分辨率到 4K 的相对跃升很大。合理的工作流程:

  1. 在较低分辨率下迭代风格指令。提示词质量与分辨率无关,因此先低成本地把效果调对。
  2. 锁定提示词和源视频。
  3. 在 4K 下重新运行一次,用于交付。

避免在调整措辞时在紧密循环中生成 4K 变体——这是把预算浪费在最终会丢弃的渲染上的最常见方式。

长时间运行的任务

更长的源视频转换耗时更久,端点返回的是任务引用而非成品文件。围绕这一现实构建你的客户端:

  • 绝不要让 Web 请求阻塞在渲染上。 提交、存储任务 id,然后立即返回给调用方。
  • 将提交与获取分离。 队列加轮询的工作进程比内联等待更健壮,且能经受进程重启。
  • 持久化任务状态。 如果工作进程在轮询中途死亡,任务不会消失;你可以从存储的 id 恢复。
  • 如果你的账户支持 webhook,请使用它,并保留轮询作为后备路径。
  • 设置总等待预算,反映你预期的最长视频,而不是一个任意数字。

一种实用模式

将超过典型时长的源视频切分为片段,逐个转换,再拼接结果。这能缩短单次等待时间,让你只重试某个片段而非整个渲染,并使失败变得廉价。务必确认片段边界不要切穿快速运动,否则接缝会很明显。

排查常见故障

大多数故障归入三类:源视频无法读取、参数被拒绝、或任务永不完成。在更改任何东西之前先隔离问题类别。

上传与源访问错误

症状:提交失败,或任务几乎立即因输入错误而失败。

  • URL 无法公开访问。 从你网络之外的机器测试它。签名 URL 在提交和抓取之间过期是典型元凶。
  • 格式不受支持。 重新编码为标准 H.264 MP4 后重试。
  • 文件被截断或损坏。 自己下载并从头到尾播放一遍。
  • 请求过大。 如果你以内联方式发送文件字节而非 URL,请改用上传流程并传入返回的标识符。

参数错误

症状:提交时返回 4xx 响应。

  • JSON 格式错误。 用 lint 工具检查请求体。尾随逗号和未转义的引号是手写 curl 调用中常见的错误。
  • 字段名或类型错误。 对照当前的请求模式;将分辨率作为数字传入而期望是字符串就会失败。
  • 提示词为空或自相矛盾。 如果指令没有描述任何东西,或要求互斥的风格,预期输出会很弱或被拒绝。围绕一个清晰的视觉方向重写。
  • API 密钥缺失或无效。 检查请求头的值,以及密钥对该端点是否有效。

超时与卡住的任务

症状:任务在你的等待预算过后仍停留在排队或运行状态,或你的客户端放弃。

  • 区分客户端超时和任务失败。提交时的短 HTTP 超时并不意味着任务没有开始;在重新提交之前检查是否有任务 id,否则可能会重复渲染。
  • 长输入和 4K 输出会延长运行时间。如果你持续超时,降低分辨率或缩短视频以确认流程可行,然后再逐步调回。
  • 如果任务报告 failed,在重试前阅读错误信息。对确定性参数错误盲目重试只会成倍增加成本。

有效的调试顺序

从尽可能小的请求开始:一段短的、标准分辨率的视频和一句提示词。如果成功,再逐一重新引入真实提示词、真实时长、最后是 4K,每次只改一个变量。出错的步骤会告诉你哪个变量是原因。

需要规划的成本与延迟权衡

请求可用之后,剩余的决策都是操作层面的。三个杠杆同时影响成本和延迟,且相互作用。

分辨率

输出分辨率是最大的单一杠杆。计费与渲染执行的工作量挂钩,更高分辨率的输出意味着更多工作量。经验法则:低分辨率迭代,高分辨率交付。绝不要让风格实验以 4K 运行。

输入时长

更长的源视频意味着更多帧需要转换,也就意味着更多算力和更多实际耗时。如果你的用例允许,转换一段较短的精华视频而不是全长剪辑,或切分长素材,只转换需要处理的部分。

重试

除非失败发生在任务开始之前,否则每次重试都是一次完整渲染。这就是调试顺序重要的原因:在花钱渲染之前低成本地验证参数。通过记录任务 id 并在客户端超时后重新提交前检查,防止重复提交。

批处理与并行

并行任务减少实际耗时但不减少总成本——且可能触及并发限制。对于批处理工作,受控并行的适度队列通常比扇出更好。它让你保持在速率限制之下,使失败易于单独重试,并给你可预测的支出曲线。

预算检查清单

  • 在任何交付渲染之前,先在低分辨率下确定提示词。
  • 缓存已完成的输出;不要重新渲染相同的输入。
  • 设置每任务和每批次的支出预期,并在批次超出时告警。
  • 跟踪任务时长与分辨率和输入时长的关系,以便从过去运行中预测新工作。
  • 将 4K 视为流程中的最后一步,而非交互模式。

该端点的定价列在 HiAPI 网站上,因此规划批次规模之前请在那里查看当前费率。先让最小请求跑通,然后再有意识地扩展分辨率和时长——这个顺序能让你的延迟和账单都保持可预测。

立即开始构建持久 AI 产物

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

阅读 API 文档