#SD2 官方满血视频生成 API 接入教程

这篇教程对应 new.thqllm.com 里的 SD2 官方满血 分组。 它和普通 SD2 教程最大的区别是：视频固定 15 秒，分辨率写在模型名里， 并且请求里必须传字符串 "seconds": "15"。

#先看懂 4 步调用流程

每次生成视频都按同一个顺序进行：

1. 选择一个带分辨率后缀的模型。
2. 提交创建请求，并保存返回的任务 ID。
3. 使用任务 ID 查询状态，等待 completed。
4. 直接使用响应里的 download_url 下载视频。

本教程所有示例都使用：

#1. 选择模型

官方满血分组一共有 4 个公开模型。模型名最后的 480p 或 720p 就是实际分辨率，不需要再传 resolution 参数。

不会选时，按下面规则判断：

• 第一次测试：使用 seedance-2.0-fast-0826-480p。
• 想要更清晰：使用 seedance-2.0-fast-0826-720p。
• 想要标准质量：使用 seedance-2.0-0826-480p 或 seedance-2.0-0826-720p。
• 想控制成本：优先选择 fast 和 480p。

generate_audio: true 不额外收费；参数校验失败不会建任务，也不会扣费。 任务进入 failed 后会按平台规则退款。

#2. 准备 API Key

1. 打开 THQ Video API 控制台并注册或登录。
2. 创建一个可用于 SD2 官方满血 分组的 API Key。
3. 将 Key 保存到环境变量中。

macOS / Linux：

export THQ_VIDEO_API_KEY="YOUR_THQ_VIDEO_API_KEY"

Windows PowerShell：

$env:THQ_VIDEO_API_KEY = "YOUR_THQ_VIDEO_API_KEY"

所有创建和查询请求都需要携带：

Authorization: Bearer YOUR_THQ_VIDEO_API_KEY

不要把真实 API Key 写入公开仓库、浏览器前端、截图、日志或发给他人。

#3. 创建第一条视频

先从最便宜的 480p 快速模型开始。注意 seconds 必须是字符串 "15"， 不是数字 15：

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: thq-video-demo-001" \
  -d '{
    "model": "seedance-2.0-fast-0826-480p",
    "prompt": "一只橘猫在窗台上打盹，阳光缓缓移动，镜头自然推进",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "generate_audio": false
  }'

请求成功后，响应里会出现 id 或 task_id。它们表示同一个视频任务。 请先保存这个值，后面查询进度要用它。

#只想换清晰度或速度？

只改 model 即可：

不要再额外传 resolution。如果传了，必须和模型名后缀一致，否则会返回 400。

#4. 等待视频生成完成

创建请求成功只表示任务已经进入队列，视频还没有生成完成。 把上一步返回的任务 ID 替换到 YOUR_TASK_ID：

curl -sS \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  "https://new.thqllm.com/v1/videos/YOUR_TASK_ID"

建议每 3-5 秒查询一次，总等待时间可以给到 600 秒。

只看 status，不要用 progress == 100 当完成信号。

成功响应大致如下：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0-fast-0826-480p",
  "seconds": "15",
  "resolution": "480p",
  "download_url": "https://new.thqllm.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
}

失败响应中通常会有错误码，例如：

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "video generation failed"
  }
}

#5. 下载视频

任务状态变成 completed 后，直接使用响应里的 download_url。不要自己拼下载地址：

curl -fL "DOWNLOAD_URL_FROM_RESPONSE" -o result.mp4

这个下载链接不需要再带 API Key，支持浏览器打开、<video> 播放、HEAD 检查和 HTTP Range 断点续传。

如果任务还没完成就访问下载链接，会返回 result_not_ready。

#6. 常用参数

支持的画面比例：

21:9   16:9   4:3   1:1   3:4   9:16   adaptive

#7. 使用参考素材

官方满血分组使用 references 数组传参考素材，不使用 multipart 文件上传。 每个素材都写成一个对象：

{
  "type": "image",
  "role": "reference",
  "source": "https://example.com/character.jpg"
}

注意：

• source 不接受 http://。
• source 不接受带用户名密码的 URL。
• 有素材时可以省略 task_mode，系统会自动判断。
• 显式写 task_mode: "text" 时不要带素材。

带参考图示例：

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-0826-720p",
    "prompt": "参考图中的角色在雪山之巅眺望远方，风吹动衣角",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "references": [
      {
        "type": "image",
        "role": "reference",
        "source": "https://example.com/character.jpg"
      }
    ]
  }'

#8. 使用分镜

分镜适合需要多个镜头的场景。每个分镜只写 prompt 和 duration， 所有分镜时长之和必须等于 15。

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-0826-720p",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "shots": [
      {"prompt": "镜头一：远景，城市天际线，夜色渐亮", "duration": 7},
      {"prompt": "镜头二：近景，人物回头看向镜头", "duration": 8}
    ]
  }'

分镜规则：

• 分镜数量为 2-15 个。
• 每个分镜只能包含 prompt 和 duration。
• 每个 duration 必须是正整数。
• 所有 duration 相加必须正好等于 15。

#9. Python 示例

安装依赖：

pip install requests

下面的示例覆盖创建、轮询和下载：

import pathlib
import time

import requests


BASE_URL = "https://new.thqllm.com"
API_KEY = "YOUR_THQ_VIDEO_API_KEY"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": "thq-video-demo-001",
}

payload = {
    "model": "seedance-2.0-fast-0826-480p",
    "prompt": "一只橘猫在窗台上打盹，阳光缓缓移动",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "generate_audio": False,
}

response = requests.post(
    f"{BASE_URL}/v1/videos",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
response.raise_for_status()
task = response.json()
task_id = task.get("id") or task["task_id"]

deadline = time.time() + 600
while time.time() < deadline:
    response = requests.get(
        f"{BASE_URL}/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()
    status = task.get("status")
    if status == "completed":
        break
    if status == "failed":
        raise RuntimeError(task.get("error") or "video generation failed")
    time.sleep(4)
else:
    raise TimeoutError("video task polling timed out")

download_url = task["download_url"]
with requests.get(download_url, stream=True, timeout=300) as response:
    response.raise_for_status()
    with pathlib.Path("result.mp4").open("wb") as output:
        for chunk in response.iter_content(1024 * 1024):
            if chunk:
                output.write(chunk)

#10. 常见问题

#seconds 传成数字了

如果看到类似下面的报错：

json: cannot unmarshal number into Go struct field .Alias.seconds of type string

说明你写成了 "seconds": 15。请改成：

"seconds": "15"

这个错误发生在请求解析阶段，不会建任务，也不会扣费。

#创建任务返回 400

优先检查这些地方：

1. model 是否填写了本页列出的 4 个模型 ID。
2. seconds 是否写成字符串 "15"。
3. 是否传了不匹配的 resolution。建议不要传 resolution。
4. aspect_ratio 是否在白名单内。
5. shots 的时长总和是否等于 15。

#创建任务返回 401 或 403

401 通常是 API Key 无效、缺失或复制错了。 403 通常是 API Key 没有开通 SD2 官方满血 分组。

#下载返回 result_not_ready

说明任务还没完成。继续查询任务状态，只有 status 为 completed 后才能下载。

#任务失败会扣费吗？

参数错误不会建任务，也不会扣费。任务进入 failed 后会按平台规则退款。 如果错误里出现 QuotaExceeded 或 429，通常是上游临时限流，建议至少等待 60 秒再重试。

#11. 避免这些常见错误

• 不要把 seconds 写成数字。
• 不要使用本页以外的模型名。
• 不要用 resolution 参数切换分辨率，直接换模型名。
• 不要自己拼下载地址，直接使用 download_url。
• 不要在 references.source 里填写 http://、本地文件路径或带账号密码的 URL。
• 不要把真实 API Key 放在前端代码、公开仓库、截图或日志里。

#12. 上线前检查

准备把调用代码用于正式项目时，请确认：

1. API Key 没有出现在前端代码、公开仓库、日志和截图中。
2. POST 创建任务时带上 Idempotency-Key，避免网络重试造成重复创建。
3. seconds 固定传字符串 "15"。
4. 模型名后缀已经匹配目标分辨率。
5. 创建任务后保存 id 或 task_id。
6. 只在状态为 completed 时下载视频。
7. 下载时原样使用 download_url。
8. 对 500、网络超时和上游限流做退避重试。

如需查看普通 SD2 模型组，请返回 SD2 接入教程。