#SD2 视频生成 API 接入教程

这篇教程面向第一次使用视频 API 的用户。你可以先完成一条最简单的文生视频请求， 确认 API Key 和调用流程正常，再按需要使用参考素材、分镜和 Python 脚本。

#先看懂 4 步调用流程

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

1. 选择模型，填写提示词。
2. 提交创建请求，并保存返回的任务 ID。
3. 使用任务 ID 查询进度，等待状态变成 completed。
4. 下载生成完成的视频。

下面是本教程会用到的地址。第一次使用时不需要全部记住，直接复制后文命令即可：

#1. 选择模型

第一次使用直接选择 firefly-video-v2-fast，并使用 5 秒、720p。 跑通第一条任务后，再根据画质、速度和分辨率需求切换其他模型。

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

• 需要 1080p：使用 firefly-video-v2。
• 需要快速测试：使用 firefly-video-v2-fast 或 leonardo-seedance-2.0-fast。
• 使用 Leonardo Seedance 2.0：将 model 改成 leonardo-seedance-2.0 或 leonardo-seedance-2.0-fast。
• 四个模型都使用 /v1/videos 创建任务，不需要更换域名或接口格式。

#2. 准备 API Key

1. 打开 THQ Video API 控制台并注册或登录。
2. 创建一个 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. 创建第一条视频

先从最简单的文生视频开始：不上传任何素材，只提交提示词。复制下面的命令即可测试：

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-video-v2-fast",
    "prompt": "雨后的城市街道，镜头平稳向前移动，霓虹灯在湿润路面形成倒影",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

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

#想换模型，只改 3 个参数

例如，使用 Leonardo Seedance 2.0 时，把请求中的 model 改为：

"model": "leonardo-seedance-2.0"

如果使用 leonardo-seedance-2.0 或 leonardo-seedance-2.0-fast，不要提交 1080p。

#不确定模型是否可用？

可以先请求模型列表。返回结果中出现的模型，才是当前账户可以调用的模型：

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

#最常用参数

JSON 请求只能提交文字参数，不能在 JSON 里放本地图片、视频或音频文件。

#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 秒查询一次，直到状态变成 completed 或 failed。

成功响应大致如下：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "model": "firefly-video-v2-fast",
  "resolution": "720p",
  "download_url": "/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
}

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

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

#5. 下载视频

状态变成 completed 后，把任务 ID 替换到下面的命令。视频会保存为当前目录下的 result.mp4：

curl -fL \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  "https://new.thqllm.com/v1/videos/YOUR_TASK_ID/content" \
  -o result.mp4

download_url 可能是相对路径。使用时将它拼接到 https://new.thqllm.com 后面即可。 下载接口同样需要 API Key，不要把带密钥的下载地址直接暴露在公开网页中。

需要检查文件信息时：

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

接口支持 HTTP Range，可用于拖动播放和断点续传。

#6. 进阶：使用参考图、视频或音频

只要请求中包含文件，就必须改用 multipart/form-data。 不要手动设置 Content-Type，让 curl 或其他 HTTP 客户端自动生成 boundary。

#文件字段怎么用

#图生视频示例

下面示例使用首帧和参考图生成视频：

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -F "model=firefly-video-v2" \
  -F "prompt=保持参考人物和场景一致，生成自然、克制的电影感运动" \
  -F "duration=10" \
  -F "resolution=720p" \
  -F "aspect_ratio=16:9" \
  -F "generate_audio=true" \
  -F "first_frame=@./first-frame.jpg" \
  -F "images=@./character-reference.png"

多个参考图重复使用同一个字段名：

-F "images=@./reference-1.jpg" \
-F "images=@./reference-2.png"

参考素材必须是真实文件，不能填写远程素材 URL、文件路径字符串、asset_id 或 JSON Base64。

#素材限制

整个 HTTP 请求最大为 384 MiB。空文件、伪造格式、重复复用同一个上传对象或未知素材字段会被拒绝。

#7. 进阶：使用分镜生成连续画面

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

curl -sS https://new.thqllm.com/v1/videos \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firefly-video-v2",
    "duration": 15,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "shots": [
      {"prompt": "广角镜头，两个人走进阳光照射的教室", "duration": 5},
      {"prompt": "中景镜头，两人在窗边交谈", "duration": 5},
      {"prompt": "近景镜头，两人相视微笑", "duration": 5}
    ]
  }'

#8. 价格说明

价格按生成时长和分辨率计费，下面是当前文档中的单价：

#Firefly Video v2

#Leonardo Seedance 2.0

价格以 THQ Video API 控制台的模型广场和任务实际扣费为准。 参数校验失败的请求不扣费；任务被确认失败后自动退款。

#9. Python 示例

安装依赖：

pip install requests

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

import pathlib
import time
from urllib.parse import urljoin

import requests


BASE_URL = "https://new.thqllm.com"
API_KEY = "YOUR_THQ_VIDEO_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

payload = {
    "model": "firefly-video-v2-fast",
    "prompt": "A steady cinematic tracking shot through a rainy city street",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": True,
}

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

deadline = time.time() + 3600
while time.time() < deadline:
    response = requests.get(
        f"{BASE_URL}/v1/videos/{task_id}",
        headers=HEADERS,
        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(5)
else:
    raise TimeoutError("video task polling timed out")

download_url = urljoin(BASE_URL + "/", task["download_url"].lstrip("/"))
with requests.get(download_url, headers=HEADERS, 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. 常见问题

#创建任务返回 401

检查请求是否包含：

Authorization: Bearer YOUR_THQ_VIDEO_API_KEY

同时确认 Key 没有复制多余空格，并且仍然处于启用状态。

#创建任务返回 400 或 422

优先检查三个地方：

1. model 是否填写了公开模型 ID。
2. resolution 是否被当前模型支持。Leonardo 模型不支持 1080p。
3. duration 是否符合模型限制。Firefly 使用 5、10、15；Leonardo 使用 5、10、14。

#一直没有 completed

任务创建成功后不要重复提交 POST 请求。保留原来的任务 ID， 每 3–5 秒查询一次；如果状态变成 failed，查看响应中的 error。

#上传素材失败

确认请求使用 multipart/form-data，字段名写对，并且传入的是实际文件。 不要使用远程素材 URL、文件路径字符串、asset_id 或 JSON Base64。

#11. 避免这些常见错误

下面这些内容来自其他平台或其他接口，不能直接用于 THQ Video API：

• 使用直连 IP、未验证域名、非公开模型名或其他服务商的接口路径。
• 把远程素材 URL、文件路径字符串、asset_id 或 JSON Base64 当作上传文件。
• 使用自签名证书、关闭证书验证或跳过 TLS 校验。
• 把账户后台接口、客户端密钥或第三方下载地址混进视频生成请求。

#12. 上线前检查

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

1. API Key 没有出现在前端代码、公开仓库、日志和截图中。
2. 创建任务后保存 id 或 task_id。
3. 只在状态为 completed 时下载视频。
4. 下载请求也携带 API Key。
5. 不使用直连 IP、非公开模型名或其他服务商的接口路径。
6. 不使用自签名证书、关闭证书验证或跳过 TLS 校验的调用方式。
7. 参数错误不会扣费，确认失败会按控制台规则退款。

如需查看接口总览，请返回 THQ Video API 概览。