视频生成

POST/v1/videos/generations

创建异步视频任务，并查询、列出或取消任务。

视频生成是异步流程。创建请求返回任务对象后，应通过任务 ID 轮询状态，直到 succeeded、failed 或 canceled。

创建任务字段

字段	类型	必填	说明
`model`	string	是	从 /v1/models 获取的视频模型 ID。
`prompt`	string	否	条件必填: 文本提示词；未提供参考图片时必须填写。
`image_url`	string	否	条件必填: 单张参考图 URL；未填写 prompt 时可由它满足输入要求。
`image_urls`	string[]	否	条件必填: 多张参考图 URL；支持情况取决于模型。
`negative_prompt`	string	否	负面提示词，仅在模型支持时生效。
`video_url`	string	否	参考视频 URL，仅在模型支持时使用。
`audio_url`	string	否	参考音频 URL，仅部分视频模型支持。
`media`	object[]	否	统一媒体输入；每项包含 type、url 和可选 role。
`duration`	integer	否	期望时长；有效值和计费档位由模型配置决定。
`ratio`	string	否	期望宽高比；可选值由模型决定。
`resolution`	string	否	期望分辨率；可选值由模型决定。
`prompt_extend`	boolean	否	是否扩展提示词，仅在模型支持时生效。
`generate_audio`	boolean	否	是否生成音频，仅在模型支持时生效。
`watermark`	boolean	否	是否包含水印，仅在 Provider 支持时生效。
`seed`	integer	否	随机种子，仅在 Provider 支持时生效。
`metadata`	object	否	调用方自定义元数据。

创建任务

创建成功返回任务 ID、状态和创建时间。某些 Provider 可能立即返回终态，但客户端仍应以 status 字段为准。

curl https://api.noxgate.net/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","prompt":"A paper airplane crossing a sunlit room","duration":5}'

{
  "id": "video_task_example",
  "object": "video.generation",
  "model": "YOUR_MODEL_ID",
  "status": "processing",
  "created": 1750000000
}

查询任务

GET/v1/videos/generations/:task_id

使用任务 ID 获取最新状态。已由平台记录的任务可省略 model；显式提供 model 时，网关会按该模型路由查询。

curl "https://api.noxgate.net/v1/videos/generations/video_task_example" \
  -H "Authorization: Bearer sk-your-api-key"

{
  "id": "video_task_example",
  "object": "video.generation",
  "model": "YOUR_MODEL_ID",
  "status": "succeeded",
  "created": 1750000000,
  "result": { "url": "https://provider.example/generated-video.mp4", "duration": 5 }
}

列出任务

GET/v1/videos/generations

列表接口要求 model 查询参数，可选 limit、after 和 status 过滤条件。

curl "https://api.noxgate.net/v1/videos/generations?model=YOUR_MODEL_ID&limit=20&status=processing" \
  -H "Authorization: Bearer sk-your-api-key"

取消任务

DELETE/v1/videos/generations/:task_id

取消接口成功返回 204 No Content。已由平台记录的任务可省略 model；能否取消取决于 Provider 当前任务状态。

curl -X DELETE "https://api.noxgate.net/v1/videos/generations/video_task_example" \
  -H "Authorization: Bearer sk-your-api-key"

任务生命周期

创建任务并保存响应中的 id。
定时调用查询接口；非终态名称可能因 Provider 而异。
succeeded 表示可读取 result.url，failed 时检查 error，canceled 表示任务已取消。
不要对轮询间隔、处理时长或结果 URL 有效期作固定假设。