外观
视频任务 API
本文中的 Bash/curl 命令用于 macOS/Linux;Windows PowerShell 的变量说明见认证与安全,JSON 请求写法见文本 API。
本文描述当前服务的 OpenAI 视频任务协议。本页保留协议参考;当前对外模型目录不列视频模型。先确认模型及分组,再提交任务;保存响应中的公开 id,查询完成后下载内容。
接口
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/videos | 新接入的主要提交入口 |
| GET | /v1/videos/{id} | 查询 OpenAI 格式状态 |
| GET | /v1/videos/{id}/content | 下载完成的视频 |
| POST | /v1/video/generations | 保留的旧提交入口;不假设它支持所有新插件 |
| GET | /v1/video/generations/{id} | 旧通用任务包装,字段及状态与 OpenAI 格式不同 |
旧入口继续存在,但客户端应固定使用一套提交、查询和下载协议,不能把原生平台状态或旧包装字段混入 OpenAI 响应处理。
提交任务
当前示例使用 JSON。Seedance 和 KW 的参考素材通过 URL 提供,不上传 multipart 文件;两者参数分别见Seedance和KW。
| 字段 | 类型 | 用途 |
|---|---|---|
model | string | 必填,当前令牌可见的模型 ID |
prompt | string | 文生视频时提供非空提示词 |
seconds | string 或 number | 视频时长;与 metadata.duration 同时出现时应保持一致 |
metadata | object | 模型专用参数,例如 resolution、ratio、generate_audio、content |
bash
curl --fail-with-body -sS "https://newapi.fq-hx.com/v1/videos" \
-H "Authorization: Bearer $FQHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"prompt": "雨后清晨的山谷,薄雾缓慢移动",
"seconds": "5",
"metadata": {
"resolution": "720p",
"ratio": "16:9",
"generate_audio": false
}
}'成功提交的结构示意:
json
{
"id": "task_xxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.0",
"status": "queued",
"progress": 0,
"created_at": 1789891200
}这是字段示意,不是本轮实测响应。HTTP 成功只说明提交成功,不等于生成完成。客户端以 id 保存任务;当前 OpenAI 查询呈现不保证 task_id 兼容字段,不能依赖它。
查询状态
bash
curl --fail-with-body -sS "https://newapi.fq-hx.com/v1/videos/task_xxxxxxxxxxxx" \
-H "Authorization: Bearer $FQHX_API_KEY"| 状态 | 是否终态 | 行为 |
|---|---|---|
queued | 否 | 继续查询原任务 |
in_progress | 否 | 继续查询原任务 |
completed | 是 | 下载 /content |
failed | 是 | 读取错误并停止查询 |
unknown | 否 | 有限次数继续查询;持续未识别时联系管理员 |
完成结构示意:
json
{
"id": "task_xxxxxxxxxxxx",
"object": "video",
"model": "seedance-2.0",
"status": "completed",
"progress": 100,
"created_at": 1789891200,
"completed_at": 1789891260
}响应可能带供应商扩展,但不保证 metadata.url 或其他上游地址字段存在。失败任务可能带 error;没有 error.message 时记录公开 id、状态和时间后联系管理员。
下载视频
bash
curl --fail -L "https://newapi.fq-hx.com/v1/videos/task_xxxxxxxxxxxx/content" \
-H "Authorization: Bearer $FQHX_API_KEY" \
-o result.mp4成功返回视频二进制,失败可能返回 JSON;下载程序应检查状态和 Content-Type,避免把错误响应保存为视频。下载后保存在自己的持久存储中。
Node.js 轮询示例
下面代码在自己的服务端运行。使用环境变量中的公开任务 ID,有限次数查询;完成后通过内容接口下载,不依赖上游 URL。请求超时或查询重试不会重新创建任务。
js
import { writeFile } from 'node:fs/promises'
const baseURL = 'https://newapi.fq-hx.com'
const taskId = process.env.FQHX_VIDEO_ID
const apiKey = process.env.FQHX_API_KEY
if (!apiKey || !/^task_[A-Za-z0-9_-]+$/.test(taskId || '')) {
throw new Error('Set FQHX_API_KEY and FQHX_VIDEO_ID to a public task ID')
}
const headers = { Authorization: `Bearer ${apiKey}` }
let delay = 5000
let completed = false
for (let attempt = 0; attempt < 60; attempt += 1) {
const response = await fetch(`${baseURL}/v1/videos/${encodeURIComponent(taskId)}`, {
headers,
signal: AbortSignal.timeout(30000),
})
if (response.status === 429 || response.status >= 500) {
// Retry the same query, never resubmit the generation request.
} else {
if (!response.ok) throw new Error(`Task query failed: HTTP ${response.status}`)
const task = await response.json()
if (task.status === 'completed') {
completed = true
break
}
if (task.status === 'failed') throw new Error(`Video task failed: ${taskId}`)
if (!['queued', 'in_progress', 'unknown'].includes(task.status)) {
throw new Error(`Unrecognized task status for ${taskId}`)
}
}
if (attempt < 59) {
await new Promise((resolve) => setTimeout(resolve, delay))
delay = Math.min(Math.round(delay * 1.5), 30000)
}
}
if (!completed) throw new Error(`Video polling timed out: ${taskId}; keep the ID for later queries`)
const content = await fetch(`${baseURL}/v1/videos/${encodeURIComponent(taskId)}/content`, {
headers,
signal: AbortSignal.timeout(120000),
})
if (!content.ok) throw new Error(`Download failed: HTTP ${content.status}`)
if (!(content.headers.get('content-type') || '').toLowerCase().startsWith('video/')) {
throw new Error('Expected video content; inspect the response before saving it')
}
await writeFile('result.mp4', new Uint8Array(await content.arrayBuffer()))网络异常会结束本次执行;保留 id,下次继续查询同一任务。生产系统还应保存业务请求 ID、模型、提交时间、终态,并按视频大小选择流式下载方案。
错误与重试
| 情况 | 处理 |
|---|---|
| 提交返回参数、认证或权限错误 | 修正请求,避免直接重复提交 |
| 提交连接超时 | 先确认任务是否已创建,避免重复生成和扣费 |
查询返回 429 或临时 5xx | 对同一任务有限次数退避重试 |
| 长时间未完成 | 保留公开 id,检查上游和任务同步状态 |
| 任务失败 | 记录脱敏错误、模型及时间;核对最终费用与退款 |
更多场景见Seedance 故障排查和错误处理。