#视频 API 接入教程

THQ Video API 通过异步任务提供视频生成能力。准备提示词与参考素材，创建任务，保存返回的完整 id， 再查询状态并使用完成响应中的 url 预览或下载视频。创建成功表示任务已受理，不表示视频已经生成；此流程不是聊天接口或 SSE 流式接口。

直接创作可使用工作台；接入应用前先确认模型、分组与参数限制。

#地址与鉴权

完整创建地址为 https://new.thqllm.com/v1/videos。使用带 /v1 的 Base URL 时只追加 /videos，避免重复拼接 /v1。 API 使用控制台创建的 API Key，不能用工作台登录 Cookie 代替。Key 的分组与模型权限决定实际可调用范围。

#接口一览

新接入统一使用 /v1/videos。视频完成后直接使用查询响应中的 url，不要再调用 /v1/videos/{id}/content 拉取文件。 完整状态与下载方式见任务查询与结果下载。

#1. 准备 API Key

登录控制台，创建用于视频调用的 Key，检查分组、模型限制与可用额度。在可信后端或本地环境中设置：

export THQ_VIDEO_BASE_URL='https://new.thqllm.com'
read -r -s -p 'THQ Video API Key: ' THQ_VIDEO_API_KEY
export THQ_VIDEO_API_KEY

本文的 THQ_VIDEO_BASE_URL 不包含 /v1；所有示例使用包含 /v1 的完整接口路径。 本地 .env 需要由应用主动加载，并排除在版本控制之外。不要把真实 Key 写进公开网页或日志。

#2. 获取并确认模型

curl --fail-with-body -sS "$THQ_VIDEO_BASE_URL/v1/models" \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY"

复制响应 data[].id 中当前 Key 可调用的视频模型 ID。模型列表用来确认可见名称， 没有提供的价格、时长、分辨率和参考素材数量应继续查看模型说明，不自行推断。

#3. 创建一次视频任务

将以下内容保存为 video-request.json，把 MODEL_ID_FROM_V1_MODELS 替换为刚才取得的完整模型 ID。 示例的 5 秒、16:9 与 720p 也需要按该模型支持范围调整：

{
  "model": "MODEL_ID_FROM_V1_MODELS",
  "prompt": "雨后的城市街道，镜头平稳前进，柔和自然光，写实电影质感",
  "seconds": "5",
  "size": "16:9",
  "resolution": "720p"
}

curl --fail-with-body -sS --max-time 180 \
  "$THQ_VIDEO_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @video-request.json \
  -o task.json

seconds 是字符串；size 直接传画面比例，resolution 独立传清晰度，不把 16:9 换算为像素尺寸。 完整字段与兼容别名见请求参数。

创建响应结构示例：

{
  "id": "task_EXAMPLE",
  "object": "video",
  "model": "MODEL_ID_FROM_V1_MODELS",
  "status": "queued",
  "progress": 0
}

保存返回的 id，查询时原样使用。部分已有兼容集成可能读取 task_id，新代码应优先读取标准响应的 id。 不要自行补上或删去 task_ 前缀，也不要截断任务 ID。

创建请求不要自动重试。 遇到超时、522、5xx 或连接中断，先查看控制台任务记录，确认是否已受理； 不要自动重发创建请求，以免重复生成和计费。

#4. 查询任务并使用结果

export THQ_VIDEO_TASK_ID='COPY_THE_RETURNED_TASK_ID'
curl --fail-with-body -sS \
  "$THQ_VIDEO_BASE_URL/v1/videos/$THQ_VIDEO_TASK_ID" \
  -H "Authorization: Bearer $THQ_VIDEO_API_KEY"

每隔 5–10 秒查询同一个任务。queued、in_progress 和 processing 均需继续等待； completed 后读取 url，failed 时查看 error.message。进度值只作提示，不能替代最终状态。

完成响应中的 url 应原样交给播放器或下载程序，无需附带 THQ API Key，也不要自行拼接文件地址。 查询失败或本地等待超时后，保留任务 ID，之后继续查询原任务。

#继续接入

• 请求参数：比例、清晰度、时长与兼容字段。
• 参考图片、视频与音频：单图、多图、音视频 URL 与文件上传。
• 任务查询与结果下载：全部状态、重试和下载检查。
• Python 与 Node.js 示例：创建一次、保存 ID、轮询并下载。
• AI 接入与 Skill：下载 THQ 接入技能并交给编程工具。
• 常见问题与错误处理：HTTP 错误、权限与工作台排错。