教程
如何通过 HiAPI API 调用 seedance-2.5-flash 参考生视频(curl + Python)
可用的请求、可运行的 Python 脚本,以及如何处理异步任务轮询
本页内容
参考生视频在实际中的含义
参考生视频是一种生成模式:你同时给模型两样东西——一段描述运动和场景的文本提示词,以及一个或多个锚定画面内容的参考素材。提示词承载意图(“缓慢推近,角色转身并微笑”),参考素材承载身份和外观(一个角色、一件产品、一种视觉风格)。
此工作流的模型端点是 seedance-2.5-flash/reference-to-video,通过 HiAPI 统一 API 提供服务。你把 model、prompt 和参考素材一起放在单个请求体中发送。没有需要你编排的单独上传步骤,也没有需要维护的逐素材注册表。
实际后果是:这是一个长时间运行的操作。一个短视频的渲染时间仍远长于文本补全,因此 API 将该调用视为异步任务。你的请求创建任务;第二次调用获取其结果。这种“先提交后轮询”的形态是你设计时最重要的一点,也是本教程其余部分要构建的方向。
以下所有内容都留在 HiAPI 接口内:一个基础 URL、一个认证头、一个端点族。
在发送第一个请求之前
首次调用前需要准备好三件事。
1. API 密钥
在 HiAPI 控制台创建密钥,并使其远离源代码管理。以下示例从环境变量读取它:
export HIAPI_API_KEY="your_key_here"
如果你不确定当前的密钥格式或请求头约定,请查看控制台中的平台 API 文档——不要猜测,也不要把密钥硬编码进你可能分享的脚本里。
2. 基础 URL 和认证头
所有调用都发往 HiAPI 基础 URL,并在 Authorization 头中携带你的密钥。将其设为变量一次,使每个请求保持一致:
export HIAPI_BASE_URL="https://api.hiapi.ai"
完全按照你账户文档所述使用基础 URL——末尾斜杠不匹配是导致令人困惑的 404 的常见原因。
3. 模型端点
你的目标是 seedance-2.5-flash/reference-to-video。在请求体中用此标识符引用它,而不是将它嵌入路径,这样以后切换模型只需改一行。
你还需要让参考素材可通过 URL 访问(或采用端点文档指定的任何素材形式)。在开始之前就将它们托管并可公开访问——损坏的参考 URL 是任务提交成功但在生成期间失败的最常见原因。
这三项设置好后,你就可以构建请求体了。
用参考素材构建请求体
请求体有三个概念部分:使用哪个模型、你想要什么、参考什么。
模型
将 model 设为 seedance-2.5-flash/reference-to-video。把它当作普通字符串字段——无需 URL 编码,无需路径段。
提示词
将提示词写成镜头描述,而不是愿望清单。说明主体、动作、镜头行为和节奏。“一个穿红色夹克的人朝镜头走来,中景,缓慢推近,柔和日光”比“一个人的好看视频”给模型的信息多得多。保持提示词与你提供的参考素材一致:如果两个参考素材展示了不同角色,说明哪个是主导。
参考素材
参考素材正是此端点与普通文生视频调用的区别所在。你传入一个或多个素材,定义跨帧应保持一致的内容。能节省迭代的实用规则:
- 使用能确定身份的最少参考素材数量。一个强参考通常胜过四个平庸的参考。
- 保持参考素材彼此一致。冲突的角度或风格会导致输出漂移。
- 优先使用干净、光照良好的源素材。裁剪过、模糊或重度滤镜的参考素材会传播这些缺陷。
- 提交前验证每个 URL 可解析——先自己抓取一次。
参考素材在请求体中究竟如何键控(数组字段名、对象结构、支持的素材类型)应来自 HiAPI 文档中端点的请求模式。根据该模式构建请求体,而不是凭记忆;该模式是字段名的权威来源,键不匹配会导致静默失败。
在请求到达网络之前,先在本地验证 JSON(python -m json.tool body.json)。格式错误的请求体是最容易捕获的错误,也是从堆栈跟踪中调试起来最烦人的错误。
可用的 curl 请求
以下命令遵循先提交后轮询模式:它创建任务并打印 JSON 响应,其中包含你将用于轮询的任务标识符。
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "一个穿红色夹克的人朝镜头走来,中景,缓慢推近,柔和日光",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
将参考 URL 替换为你自己托管的素材,并在生产环境依赖此代码之前,对照 HiAPI 文档中的模型页面确认端点路径和字段名——模式细节具有权威性,此片段仅供说明。
响应中要关注的内容:
- 一个 id(或 task/job 标识符)——捕获它;每次轮询都需要它。
- 一个 status 字段,表示任务已被接受。
- 任何关于被忽略或拒绝的素材的警告。
为便于阅读,美化打印它:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
将请求体保存在 body.json 中值得这一小步额外付出:它能干净地进行版本控制、可读地对比差异,并从调试范围中移除 shell 引号错误。
Python 中的相同调用
以下是 Python 中的等效调用,编写为在设置环境变量后可直接运行。它仅使用标准库,因此无需安装任何东西。
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="一个穿红色夹克的人朝镜头走来,中景,缓慢推近,柔和日光",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
两个细节比看起来更重要。第一,timeout=60——提交调用应快速返回,但挂起的连接比快速失败更糟。第二,result.get("id") 处理响应结构出乎意料的情况,而不是在你的正常路径中抛出 KeyError。
如果你更喜欢 requests 或 httpx,转换很直接:相同的 URL、相同的请求头、相同的 JSON 请求体。请求体的构建是值得复制的部分;HTTP 客户端是可替换的。
轮询异步任务直到完成
视频生成不是你可以等待的请求。你提交、拿回标识符,然后定期检查状态,直到任务达到终止状态。两个特性使这安全:轮询开销低,而提交调用已经完成了昂贵的工作。
循环
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
更紧凑的循环不会更快;它只会消耗速率限制。对于视频任务,五秒间隔是合理的默认值。
设计说明
- 始终设置截止时间。永不终止的任务绝不能永远挂起请求线程。
- 将未知状态视为“继续等待”,而不是成功。只有明确的成功才是成功。
- 不要在 Web 请求处理程序内轮询。在处理程序中提交,将任务 id 返回给客户端,让后台工作进程轮询并持久化结果。
- 持久化任务 id 和状态转换,使中断的进程能够恢复,而不是重新提交并支付两次渲染费用。
这种先提交后轮询的拆分,正是让缓慢的视频流水线能够位于快速 API 背后的原因。
常见错误及其修复方法
第一个小时内几乎每个失败都归入四个类别之一。按此顺序检查它们。
1. 认证
症状:在创建任何任务之前出现未授权或禁止的响应。
检查:运行脚本的 shell 或进程中 HIAPI_API_KEY 是否确实已填充?请求头是否恰好是 Authorization: Bearer <key>?你是否在导入时加载密钥,而脚本期望稍后使用?打印解析后密钥的前几个字符(绝不打印整个密钥),并确认它不是空字符串。
2. 端点路径
症状:未找到,通常是立即出现。
检查:基础 URL 加路径之间恰好一个斜杠——这就是 Python 示例调用 .rstrip("/") 的原因。对照文档中的模型页面确认生成路径和轮询路径;缺少任务 id 段的轮询 URL 每次都会 404。服务器不期望的末尾斜杠会产生相同症状。
3. 格式错误的请求体
症状:验证错误,或任务被接受后立即失败。
检查:运行 json.dumps(body) 并检查它。model 是否与 seedance-2.5-flash/reference-to-video 完全匹配?参考字段是否是数组,且每个条目是否是在浏览器中可解析的字符串 URL?你是否发送了 Content-Type: application/json?让请求体通过 python -m json.tool,以便在到达网络之前排除语法错误。
4. 任务状态
症状:提交调用成功,但任务失败或永不完成。
检查:读取状态响应中的错误字段——它通常会指出原因,最常见的是不可达或不支持的参考素材。如果任务只是停在那里,确认你轮询的是正确的 id,并且循环的状态比较覆盖了 API 实际返回的终止状态。记录每个状态转换;失败前的最后一个状态就是你的诊断依据。
一条能缩短所有四类排查的规则:为每次调用记录请求 id 和任务 id。当出现故障时,一个 id 能将模糊的错误报告变成具体的查找。
下一步
你现在已掌握完整形态:用提示词和参考素材构建请求体、提交它、轮询直到终止,并处理四类常见失败。从这里开始,自然的下一步是工程层面的,而不是 API 层面的。
- 用带退避的重试包装提交以应对瞬态网络错误,但绝不要重试已有 id 的任务——那是重复渲染。
- 将轮询移入工作进程或队列,使 HTTP 层保持响应,任务能在进程重启后存活。
- 将任务 id 与你自己的请求元数据一起存储(提示词、参考素材、请求用户),以便数月后结果仍可追溯。
- 在验证之后才放行参考素材——当用户提供每个 URL 时抓取它,然后再花费任务。
有关权威请求模式、支持的素材形式和当前端点细节,请参阅 HiAPI 上的 seedance-2.5-flash 参考生视频模型页面。基于该模式构建,保持先提交后轮询的拆分,集成就会保持平淡无奇——这正是你希望从视频流水线中得到的东西。