教程
如何通过 HiAPI API 调用 wan2.7-video 文生视频:curl 与 Python
本页内容
本教程将要构建的内容
读完本指南,你将拥有一个可工作的小型流水线:通过 HiAPI API 向 wan2.7-video/text-to-video 提交一个文生视频任务——先用 curl 实现一次,再用 Python 实现一次——然后等待视频生成完成。
这两次调用是刻意保持等价的。curl 版本是参照实现,你可以把它粘贴进终端,用来确认凭据和请求体是否正确。Python 版本把同一个请求封装成一个函数,便于放进脚本或服务中,并包含轮询、错误处理和合理的默认值。
由于视频生成远慢于聊天补全,整个流程是异步的:先提交任务,拿到一个标识符,然后轮询直到任务报告终态。下文都围绕这一生命周期组织,因此如果你之后改用图生视频,或同一端点族下的其他视频模型,整体结构依然适用。
发送第一个请求之前
首次调用要成功,需要先满足三个条件。
凭据
你需要一个 HiAPI API 密钥,通过 Authorization 请求头以 bearer token 形式发送。请把它放在环境变量中,而不是写进源码:
export HIAPI_API_KEY="your-key-here"
已知的模型标识符
模型标识符是精确字符串。本教程中该值为 wan2.7-video/text-to-video——包含任务后缀。近似写法如 wan2.7-video 或 wan2.7/text-to-video 会被拒绝,因此请从模型列表中复制标识符,不要凭记忆手写。
一个可供评估的提示词
盲目迭代视频生成的代价很高。请提前写好一个具体的提示词(主体、动作、镜头行为、光照、风格),这样当结果返回时,你可以判断需要调整的是这些设置,而不是措辞。
你还需要一个 HTTP 客户端和一种读取 JSON 的方式。shell 侧用 curl 加 jq;脚本侧用 Python 加 requests。
请求体的结构解析
一个文生视频请求就是一个 JSON 对象,字段可分为三组。
身份
model——精确的模型标识符,即wan2.7-video/text-to-video。
内容
prompt——描述你想要的视频的文本。这是起主要作用的字段;请具体说明运动、构图和风格,而不是堆砌形容词。negative_prompt——可选。描述不应出现的内容。对抑制常见瑕疵很有用,但不能替代写好的提示词。
生成设置
duration——输出片段的时长。resolution——输出的尺寸/分辨率档位。seed——可选。当你想在稳定起点下比较两个提示词或两次设置变更时,将其固定。
最小请求体只需要 model 和 prompt;平台会为其余字段应用默认值。但默认值不等于你所做的选择——关于为什么在生产环境中应显式设置,请参阅下文的时长与分辨率部分。
请保持请求体扁平、浅层。只对真正属于子对象的字段进行嵌套,可以让请求更易读,也更容易发现 schema 错误。
用 curl 提交任务
下面是一个完整的提交示例。该端点接收 JSON,并返回任务句柄而非视频本身。
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "夜晚雨湿的霓虹小巷中缓慢推进的跟拍镜头,地面上有反光水洼,浅景深,电影级调色",
"duration": 5,
"resolution": "720p"
}'
提交成功后返回一个对象,包含任务或作业标识符以及状态。结构大致如下:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
有两点需要注意。第一,status 不是 succeeded——此时还没有渲染任何内容。第二,响应中没有视频 URL。该 URL 只在任务达到终态后出现。
如果你想把标识符留在 shell 会话中供轮询步骤使用:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
把请求体移进 payload.json 能让命令保持简短,也便于在多次运行之间调整提示词。
用 Python 提交任务
Python 版本是同一个请求,只是用起来更顺手。在 curl 中是请求头或 JSON 键的内容,在这里都变成了关键字参数。
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"夜晚雨湿的霓虹小巷中缓慢推进的跟拍镜头,"
"地面上有反光水洼,浅景深,电影级调色"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
与 shell 版本的对应关系是一一对应的:
-H "Authorization: ..."→HEADERS字典。-d '<json>'→json=payload。传入字典而非字符串意味着由requests负责序列化,因此不会误发格式错误的 JSON。- 用
jq提取的.id→job["id"]。
有两个 Python 特有的习惯值得现在就养成。始终为提交调用设置 timeout——该请求很小,应很快返回,因此长时间挂起意味着连接出了问题,而不是渲染。并在读取响应体之前调用 raise_for_status(),这样 HTTP 层失败会给出清晰的 traceback,而不是在 job["id"] 上抛出令人困惑的 KeyError。
处理异步任务与轮询
轮询是大多数集成要么变得稳健、要么变得不稳定的环节。任务有生命周期——通常是排队、处理中,然后是成功或失败的终态——你的循环必须处理这三种情况。
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
这个循环里有几个设计要点,其重要性比看上去更大:
显式检查终态。把所有非 succeeded 的状态都当作“继续等待”,意味着失败的任务会悄悄耗尽你全部的轮询预算。应当匹配失败状态并抛出异常。
有意识地选择轮询间隔。视频渲染需要数十秒到数分钟。每 200 毫秒轮询一次只会增加负载,而且不会告诉你任何新信息。从 5 秒左右开始;如果任务经常运行很久,应增大间隔而不是增加尝试次数。
始终为循环设上限。max_attempts 上限能把无限挂起转化为可诊断的 TimeoutError。同时记录任务 ID——那是你排查问题时需要的值。
遵守速率限制。如果批量提交,不要同时发出所有轮询请求。使用按固定间隔运行的共享轮询器,或简单的客户端限流,能让你保持在限制之内。
成功时,响应会包含已完成资产的位置。请立即下载它,不要把任务记录当作永久存储。
选择时长与分辨率
这两个设置对输出的影响超过其他任何参数,而且它们都影响任务运行时长和费用。计费用量以输出秒数计算,而分辨率决定每秒的工作量——因此请把两者都视为针对具体用例的有意选择,而不是可以留在默认值的字段。
时长
更长的片段给动作留出发展空间,但每一秒额外时长都意味着更多渲染和更高成本,长时生成也更容易出现连贯性问题。实用建议:
- 短(几秒)——社交循环、产品主视觉、B-roll。迭代成本最低,也最容易判断。
- 中等——叙事节拍、建立镜头。
- 长——只在故事确实需要时使用。如果你需要长视频,考虑生成多个短片段再剪辑组合;这通常比一次长渲染更便宜,也给你更多控制权。
在迭代提示词时,生成模型允许的最短片段。在这个长度上判断构图和运动,满意后再延长时间。
分辨率
更高分辨率意味着每帧更多像素、更长渲染时间和更高成本。但在小屏幕上,它的重要性比你想象的要低。1080p 母版适合交付给客户;720p(或更低)草稿适合判断提示词是否有效。
高效的模式是两阶段工作流:在低分辨率下锁定提示词和时长,然后按交付分辨率重新运行最终任务。不要在最高设置下迭代——你会把大部分预算花在丢弃的素材上。
排查常见错误
大多数失败源于请求的组织方式,而不是模型本身。在对模型能力下结论之前,请按顺序排查以下几类问题。
401 / 403——凭据问题
检查密钥是否设置在进程实际可见的环境中(在一个 shell 中导出的密钥对 systemd 服务不可见),检查请求头是否为 Authorization: Bearer <key>,并检查变量中没有尾部空白。调试时只打印密钥的前几个字符,绝不要打印完整密钥。
404——路径或模型错误
端点路径和模型标识符是两回事,两者都必须精确。确认你 POST 的 URL,并确认 wan2.7-video/text-to-video 是从模型列表逐字符复制的。有效的密钥配上错误的模型字符串仍会返回类似 not-found 的错误。
400——请求体格式错误
这是最常见的一类。常见原因包括:像 duration 这样的数值字段被作为字符串 "5" 发送,提示词被作为列表而非字符串发送,或请求体被意外双重编码。最快的分诊方法是重新发送完全相同的 curl 命令——如果 shell 调用成功而 Python 调用失败,问题出在脚本构建字典的方式,而不是请求本身。
422 / 校验错误
语法有效但语义有问题:时长超出支持范围、未知的分辨率档位,或缺少必填字段。阅读错误信息——它通常会指出有问题的字段。
提交后任务失败
提交调用成功,但渲染没有成功。这可能是内容策略拒绝,也可能是临时渲染失败。记录任务 ID 和错误负载;如果是临时性问题,重新提交相同负载是合理的第一步。如果同一提示词反复出现,应改变提示词措辞或生成设置,而不是反复重试同一个请求。
轮询始终不结束
如果任务在处理中停留的时间远超同类任务,应停止轮询,记录任务 ID,并将其视为失败任务。长尾情况足够罕见,带有明确错误信息的有界超时比开放循环更好。
遇到每个新问题时,都先从 curl 参照实现开始:它把你的代码从问题中排除,从而隔离出问题出在请求还是客户端。