视频任务 API

本站通过统一异步接口提交视频生成任务。客户端必须保存提交响应中的公开任务 ID，并使用查询接口获取状态和结果。

基础信息

Base URL: https://newapi.fq-hx.com
Authorization: Bearer <NEWAPI_API_KEY>
Content-Type: application/json

方法	路径	说明
POST	/v1/video/generations	提交视频生成任务
POST	/v1/videos	OpenAI 兼容提交入口
GET	/v1/videos/{task_id}	查询 OpenAI 兼容格式任务状态
GET	/v1/video/generations/{task_id}	查询 NewAPI 通用任务数据
GET	/v1/videos/{task_id}/content	获取已完成的视频内容

推荐接口组合

新接入建议使用 POST /v1/video/generations 提交，以 GET /v1/videos/{task_id} 查询状态。两者返回的都是本站公开任务 ID，不暴露上游任务号。

POST /v1/video/generations

提交一个视频生成任务。

请求字段

字段	类型	必需	说明
model	string	是	模型名称或本站配置的模型别名
prompt	string	是	视频生成提示词，不能为空
image	string	否	单张参考图 URL；内部会转换为 images
images	string[]	否	多张参考图 URL
seconds	string	否	部分适配器使用的通用时长字段
size	string	否	部分适配器使用的通用尺寸字段
metadata	object	否	渠道专用参数；Seedance 的时长、分辨率、比例等放在这里

不同渠道只读取其支持的字段。Seedance 的完整 metadata 参数见 火山引擎 Seedance。

最小请求

curl -sS "https://newapi.fq-hx.com/v1/video/generations" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "雨后清晨的山谷，薄雾缓慢移动",
    "metadata": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": false
    }
  }'

成功响应

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1789891200
}

字段	类型	说明
id	string	本站公开任务 ID，后续查询使用此值
task_id	string	兼容字段，当前与 id 相同
object	string	固定为 video
model	string	客户端请求的模型名称
status	string	初始通常为 queued
progress	integer	0～100 的进度值
created_at	integer	Unix 时间戳

HTTP 200 只表示任务已经成功提交，不表示视频已经生成。

GET /v1/videos/{task_id}

查询 OpenAI 兼容格式的任务状态。

curl -sS "https://newapi.fq-hx.com/v1/videos/task_xxxxxxxxxxxx" \
  -H "Authorization: Bearer $NEWAPI_API_KEY"

状态枚举

状态	是否终态	说明
queued	否	已提交或正在排队
in_progress	否	上游正在生成
completed	是	已完成，可获取结果
failed	是	失败，读取 error
unknown	否	未识别状态，应降低频率继续查询或联系管理员

完成响应

{
  "id": "task_xxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1789891200,
  "completed_at": 1789891260,
  "metadata": {
    "url": "https://上游返回的临时地址"
  }
}

失败响应

{
  "id": "task_xxxxxxxxxxxx",
  "object": "video",
  "model": "seedance-2.0",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "upstream_error_code",
    "message": "上游返回的失败原因"
  }
}

GET /v1/video/generations/{task_id}

该接口返回 NewAPI 通用任务包装，适合需要查看平台、渠道、额度、原始状态和任务时间的客户端。

curl -sS "https://newapi.fq-hx.com/v1/video/generations/task_xxxxxxxxxxxx" \
  -H "Authorization: Bearer $NEWAPI_API_KEY"

响应结构：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "platform": "54",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://上游返回的临时地址",
    "fail_reason": "",
    "created_at": 1789891200,
    "updated_at": 1789891260
  }
}

通用接口状态使用大写内部枚举，例如 QUEUED、IN_PROGRESS、SUCCESS、FAILURE。如果不需要内部任务字段，优先使用 /v1/videos/{task_id}。

GET /v1/videos/{task_id}/content

任务完成后，通过本站代理获取视频内容：

curl -L "https://newapi.fq-hx.com/v1/videos/task_xxxxxxxxxxxx/content" \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -o result.mp4

响应为视频二进制流，而不是 JSON。任务尚未完成、任务不存在或不属于当前用户时会返回 JSON 错误。

轮询实现

推荐初始间隔 5 秒，逐步增加到 30 秒，并设置总超时。不要因为任务仍在排队而重新提交。

const baseURL = 'https://newapi.fq-hx.com'
const taskId = 'task_xxxxxxxxxxxx'
let delay = 5000

for (let attempt = 0; attempt < 60; attempt += 1) {
  await new Promise((resolve) => setTimeout(resolve, delay))

  const response = await fetch(`${baseURL}/v1/videos/${taskId}`, {
    headers: { Authorization: `Bearer ${process.env.NEWAPI_API_KEY}` },
  })

  if (!response.ok) {
    throw new Error(`${response.status}: ${await response.text()}`)
  }

  const task = await response.json()
  if (task.status === 'completed') {
    console.log(task.metadata?.url)
    break
  }
  if (task.status === 'failed') {
    throw new Error(task.error?.message || 'video generation failed')
  }

  delay = Math.min(Math.round(delay * 1.5), 30000)
}

生产系统还应持久化 task_id、提交时间、模型、业务请求 ID 和最终状态，以便进程重启后继续查询。

错误与重试

情况	客户端行为
提交返回 4xx	修正认证、权限、模型或参数，不直接重试
提交返回 429	检查额度与限流，指数退避
提交连接超时	无法确认是否创建任务时不要无限重试，应结合业务幂等记录排查
查询返回 queued / in_progress	继续轮询原任务，不重新提交
查询返回 failed	记录公开任务 ID、错误代码和脱敏消息
临时 5xx	对同一查询有限次数重试，不创建新任务

更多场景见火山引擎视频故障排查和错误处理。