教程

如何通过 hiapi API 使用 seedance-2.0-fast：curl、Python 与可运行的请求

2026年11月3日

本指南展示用 seedance-2.0-fast 生成视频的最小请求、该模型实际接受的全部输入字段，以及如何通过轮询或回调等待结果。下面的每个请求结构和错误消息都已在真实 API 上运行验证过，因此你可以直接复制代码使用。

你将构建什么，以及需要准备什么

目标只有一个：发送一段文本提示词，拿回一个可下载的 MP4 URL。seedance-2.0-fast 是 Seedance 2.0 的速度优化版本——它以牺牲最高分辨率（上限为 720p）换取更快的生成速度，因此非常适合预览、迭代循环以及大批量短视频片段。

你只需要一样东西：一个 hiapi API 密钥。请从你的仪表盘获取，它的格式形如 sk-...。所有视频模型（包括这个）都通过统一的异步任务端点提供服务：你先 POST /v1/tasks 创建任务，然后通过任务 id 获取结果。视频没有同步模式。

当前的单个片段价格见价格页面（该模型刚刚上线，所以请以那里为准，不要轻信博客文章里的任何数字）。

最小可运行示例（curl）

创建任务：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked street at dusk, cinematic, slow dolly-in",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

响应中的任务 id 位于 data.taskId：

{
  "data": {
    "taskId": "task_abc123..."
  }
}

轮询该任务，直到状态变为终态：

curl "https://api.hiapi.ai/v1/tasks/task_abc123..." \
  -H "Authorization: Bearer sk-YOUR_KEY"

当 data.status 为 "success" 时，视频 URL 位于 data.output[0].url。该 URL 是带签名的，会过期——请立即下载文件，不要热链接：

curl -o clip.mp4 "<the output url>"

所有输入字段（已核实）

只有 prompt 是必填的。不在此表中的任何字段都会以 400 被拒绝——该 schema 不允许额外属性。

字段	类型	必填	接受的值
`prompt`	string	是	最小长度 3 个字符
`duration`	整数	否	4–15（秒）
`resolution`	string	否	`480p`、`720p`
`aspect_ratio`	string	否	`1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`21:9`、`adaptive`

有两点值得特别说明：

duration 是整数，不是字符串。发送 "duration": "5" 会校验失败，报错为 duration: got string, want integer。
没有图像输入。seedance-2.0-fast 仅支持文生视频；像 image_urls 这样的字段会被 schema 拒绝。如果你需要图生视频，请参阅图生视频 API 工作流指南，了解支持该功能的模型。

Python 中的相同流程

无需 SDK——requests 就够了：

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "A barista pours latte art in a sunlit cafe, shallow depth of field"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# The URL is signed and expires — persist the bytes immediately.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

把除 success / fail 之外的任何状态都当作"仍在运行"——这样即使中间状态名称将来发生变化，循环也依然稳健。

生产环境注意事项

用回调替代轮询

对于脚本之外的任何场景，在创建任务时注册回调，从而完全跳过轮询：

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

使用 "when": "final" 时，当任务达到终态，你的端点会恰好收到一次 POST。轮询适用于 CLI 和 notebook；当你大规模运行时，回调更胜一筹（没有浪费的请求，也没有轮询间隔带来的延迟）。如果你的钩子似乎没有触发，请查阅回调故障排查指南——几乎总是 URL 可达性问题或你的处理器返回了非 2xx 响应。

幂等性

创建任务不是免费的，所以要在你这一侧防止重复提交：让每个业务事件最多对应一次 POST /v1/tasks 调用（例如，在重试前将 taskId 与你的订单/任务行关联存储）。如果你的进程在创建任务后崩溃，可以通过重新读取已存储的 taskId 并恢复 GET /v1/tasks/<id> 来恢复——无论你是否轮询，任务都会在服务端继续运行。

你实际会遇到的错误

症状	含义	修复
`400` 且 `error_code: "INVALID_REQUEST"`	输入未通过 schema 校验；`message` 会指明具体字段，例如 `duration: maximum: got 20, want 15`	修正该字段；只允许上表中的四个字段
`401` 且 `error.code: "permission_denied"`	密钥无效，或有效但未为该模型启用	在仪表盘中检查密钥；模型权限是按密钥分别设置的
GET 时 `404` 且 `"task not found"`	任务 id 错误或不属于该账户	使用创建时返回的 `taskId`，且属同一账户
任务状态为 `"fail"` 且带有 `error` 对象	生成本身失败	读取 `error.code`/`error.message`；调整提示词后重试

注意两种错误封装：校验错误将 message 放在顶层，而鉴权错误嵌套在 error 下。如果你编写通用中间件，需要同时处理这两种情况。

seedance-2.0-fast 的适用场景

如果你需要 1080p 或 4K 输出，请改用完整的 seedance-2.0——相同的端点、相同的流程、更高的分辨率上限（且它要求显式指定 aspect_ratio）。如需更全面地了解 Seedance 系列与平台上其他视频模型的对比，请参阅视频模型对比。每个模型的完整参数参考见文档，模型页面会跟踪当前能力与定价状态。

常见问题

seedance-2.0-fast 支持哪些分辨率？ 480p 和 720p。这就是为速度付出的代价——完整的 seedance-2.0 在相同的 /v1/tasks 流程下最高可达 1080p 和 4k。

我可以用 seedance-2.0-fast 做图生视频吗？ 不能。输入 schema 只接受 prompt、duration、resolution 和 aspect_ratio；图像字段会被校验错误拒绝。关于 hiapi 上的图生视频选项，请参阅图生视频工作流指南。

生成的视频可以有多长？ duration 接受 4 到 15 秒的整数。超出该范围的值会在创建任务前校验失败（被拒绝的请求不会计费）。

我应该轮询还是使用回调？ 对于脚本和低并发量，每 ~5 秒轮询一次即可。在生产规模下，在创建时传入 callback: {"url": ..., "when": "final"}，让 hiapi 将终态推送给你——一次请求而非数十次。

为什么一个对其他模型有效的密钥，在这里会得到 401 permission_denied？ 模型访问权限是按密钥分别限定范围的。在此模型上出现 401 且 permission_denied，意味着密钥存在但未为 seedance-2.0-fast 启用——请在仪表盘中检查该密钥的模型权限。

输出 URL 的有效期是多久？ 它是带签名的 URL，会过期。任务成功后立即下载 MP4 并自行存储；不要将原始输出 URL 嵌入任何长期存在的地方。