博客

教程

如何通过 HiAPI API 调用 seedance-2.5-flash 参考生视频(curl + Python)

可用的请求、可运行的 Python 脚本,以及如何处理异步任务轮询

2026年11月19日
极简建筑风格封面图:暖灰色混凝土平面以斜射日光角度交错,一块深蓝灰色阴影面与一条细鼠尾草绿接缝点缀。
本页内容

参考生视频在实际中的含义

参考生视频是一种生成模式:你同时给模型两样东西——一段描述运动和场景的文本提示词,以及一个或多个锚定画面内容的参考素材。提示词承载意图(“缓慢推近,角色转身并微笑”),参考素材承载身份和外观(一个角色、一件产品、一种视觉风格)。

此工作流的模型端点是 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 参考生视频模型页面。基于该模式构建,保持先提交后轮询的拆分,集成就会保持平淡无奇——这正是你希望从视频流水线中得到的东西。

立即开始构建持久 AI 产物

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

阅读 API 文档