创建视频生成

从源码生成 POST /video-generations 的鉴权、字段、响应、错误与安全调用参考。

公开测试API v1 · 1.3.0最后核实 2026-08-30

本页目录

操作

POST /video-generations

operationId: create_video_generation_v1_video_generations_post

启动付费异步任务。先报价并取得用户批准，立即保存任务 ID；202 仅代表已接受。响应不明时复用同一幂等键、凭据身份与未修改的请求。创建时重新计价；API 报价不锁价，max_credits/quote_id 不是 API 请求字段。遵循 Retry-After 轮询，所有终态（包括失败）都需检查 outputs。

鉴权与副作用

使用可信环境中的 Bearer API Key。所需权限：animations:write

此操作创建付费任务，提交前取得批准。API 报价不锁价，也不强制执行最高预算。

参数

参数	位置	类型	必填	约束 / 默认值	含义
`Idempotency-Key`	`header`	`string`	是	`minLength`: `8`; `maxLength`: `200`	每次逻辑操作生成并保存一次；同一凭据和未修改请求重试时复用，更换凭据会改变去重范围。

请求体 (application/json)

请求体必填：true

字段	类型	必填	默认值	约束	含义
`input`	GenerationInput	是	—	—	调用方所属或本次提供的生成图片。
`metadata`	`object`	否	`{}`	—	调用方元数据，仅字符串、数字、布尔或 null；JSON 不超过 4 KiB，不存凭据。
`negative_prompt`	`string`	否	`""`	`maxLength`: `4000`	可选负向提示词，仅适用于支持的模型。
`prompt`	`string`	否	`""`	`maxLength`: `8000`	动作提示词；模型要求时不能为空，私有提示词不得写入日志。
`video`	VideoOptions	否	`{"duration_seconds":null,"input_canvas":null,"model":null,"ratio":null,"resolution":null,"seed":null,"style_preset":null,"transparency":{"key_color":null,"key_selection":"auto","mode":"standard"},"watermark":null}`	—	符合模型能力的生成设置。

完整嵌套结构：VideoGenerationCreateRequest

请求示例

json

{
  "input": {
    "first_frame": {
      "file_id": "00000000-0000-4000-8000-000000000001",
      "type": "file"
    }
  },
  "prompt": "A character runs in place, side view, fixed camera."
}

响应

HTTP	正文	含义
`202`	TaskResponse	已接受异步任务，请保存任务 ID 并轮询。
`400`	APIErrorEnvelope	输入错误，修正请求后再尝试。
`401`	APIErrorEnvelope	API Key 缺失、到期或被撤销。
`402`	APIErrorEnvelope	积分不足，不自动购买。
`403`	APIErrorEnvelope	账户资格、账户状态或 Key 权限不允许此操作。
`404`	APIErrorEnvelope	资源不可用、不属于当前用户，或签名无效/过期。
`409`	APIErrorEnvelope	幂等冲突；仅 IDEMPOTENCY_IN_PROGRESS 可复用原请求重试。
`413`	APIErrorEnvelope	请求或解码后的图片超过配置限制。
`415`	APIErrorEnvelope	使用支持的图片媒体类型。
`422`	APIErrorEnvelope	图片解码后尺寸超过限制。
`429`	APIErrorEnvelope	触发账户级速率或队列限制，遵循 Retry-After 等待。
`500`	APIErrorEnvelope	内部错误，保留任务 ID 和幂等键，仅标记可重试时重试。
`503`	APIErrorEnvelope	服务或供应商不可用，仅 error.retryable 为 true 时重试。

响应头

HTTP	响应头	类型	含义
`202`	`Retry-After`	`integer`	建议等待秒数，遵循服务值并设置总体截止时间。
`429`	`Retry-After`	`integer`	建议等待秒数，遵循服务值并设置总体截止时间。
`503`	`Retry-After`	`integer`	建议等待秒数，遵循服务值并设置总体截止时间。

响应示例

json

{
  "created_at": "2026-08-30T00:00:00Z",
  "credits": {
    "charged": 0,
    "held": 1,
    "quoted": 1
  },
  "error": null,
  "finished_at": null,
  "id": "00000000-0000-4000-8000-000000000002",
  "metadata": {},
  "normalized_input": {},
  "object": "video_generation",
  "outputs": [],
  "progress": 0,
  "stage": "queued",
  "started_at": null,
  "status": "queued"
}

这篇文档有帮助吗？

允许文档使用分析

不收集搜索词、代码或自由文本。此开关只控制文档交互事件；站点通用分析仍遵循隐私政策。隐私政策

需要帮助？联系支持

搜索文档