Skip to content

视频任务 API ​

本文中的 Bash/curl 命令用于 macOS/Linux;Windows PowerShell 的变量说明见认证与安全,JSON 请求写法见文本 API。

本文描述当前服务的 OpenAI 视频任务协议。本页保留协议参考;当前对外模型目录不列视频模型。先确认模型及分组,再提交任务;保存响应中的公开 id,查询完成后下载内容。

当前验证范围

本轮更新核对了服务 v1.0.0-rc.47 的路由、插件和响应呈现代码,未发起计费视频请求。模型状态及配置核对日期见模型目录。KW 模型存在插件绑定待核对项。

接口 ​

方法路径说明
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。

字段类型用途
modelstring必填,当前令牌可见的模型 ID
promptstring文生视频时提供非空提示词
secondsstring 或 number视频时长;与 metadata.duration 同时出现时应保持一致
metadataobject模型专用参数,例如 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 故障排查和错误处理。

本站提供 FQHX 接入说明;模型能力与审核规则以上游平台最新规定为准。