Skip to main content
POST
/
v1
/
videos
Error
A valid request URL is required to generate request examples
{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1761234567,
  "status": "queued",
  "model": "veo-3.1-fast-generate-preview",
  "prompt": "A cinematic lion at sunset",
  "progress": 0,
  "seconds": 6,
  "size": "1280x720"
}
通过 /v1/videos 创建 OpenAI 兼容的 Sora 视频任务。本文只描述 OpenAI 官方契约；关于 kapon 的模型分组路由、经济型分组与第三方兼容渠道差异、平台扩展字段，请参考 Sora 视频路由与分组。

​
官方参考

​
创建视频任务

​
multipart/form-data

当你需要直接上传参考图文件时，使用 multipart 表单： 
curl -X POST "https://models.kapon.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=sora-2" \
  -F "prompt=百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富" \
  -F "seconds=8" \
  -F "size=720x1280" \
  -F "input_reference=@/absolute/path/to/ref.jpg"

​
application/json

当你使用 JSON 请求体时，input_reference 应为单个对象，而不是数组： 
curl -X POST "https://models.kapon.cloud/v1/videos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "百事可乐宣传片，都市街拍风，年轻活力，镜头运动丰富",
    "seconds": 8,
    "size": "720x1280",
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'
input_reference 的官方 JSON 结构是单个对象，例如 { "image_url": "..." } 或 { "file_id": "..." }；不要传 ["https://..."] 这样的数组。

​
请求字段

  • model：模型名称，例如 sora-2、sora-2-pro
  • prompt：视频生成提示词
  • seconds：使用当前 OpenAI 官方文档允许的时长值。当前 API Reference 公开了 4、8、12；Video Generation Guide 还描述了部分官方 Sora 2 / Sora 2 Pro 工作流中的更长时长。请以你配置的官方渠道实际支持能力为准。
  • size：使用当前 OpenAI 官方文档允许的分辨率值。当前 API Reference 列出 720x1280、1280x720、1024x1792、1792x1024；Video Generation Guide 还描述了部分官方 sora-2-pro 工作流中的 1920x1080、1080x1920。
  • input_reference：
    • multipart/form-data 下：单个文件字段
    • application/json 下：单个对象，例如 {"image_url":"..."} 或 {"file_id":"file_..."}

​
响应示例

{
  "id": "video_691209aab0a08198a4e78870277f7e3d0215e09cec47a737",
  "object": "video",
  "created_at": 1762789802,
  "status": "queued",
  "model": "sora-2",
  "prompt": "百事可乐宣传片",
  "progress": 0,
  "seconds": "8",
  "size": "720x1280"
}

​
官方工作流

  1. 创建任务：POST /v1/videos
  2. 查询状态：GET /v1/videos/{video_id}，见 视频查询
  3. 下载结果：GET /v1/videos/{video_id}/content，见 视频下载
如果你对外承诺“OpenAI 官方兼容”，请把这份页面视为公开契约边界；经济型分组的时长槽位、宽高比别名和角色扩展字段不应继续写入 OpenAI 主文档。

Authorizations

​
Authorization
string
header
required

API Key

Body

​
model
enum<string>
required

模型名称

Available options:
veo-3.1-generate-preview,
veo-3.1-fast-generate-preview
Example:

"veo-3.1-fast-generate-preview"

​
prompt
string
required

文本提示词

Example:

"A cinematic lion at sunset"

​
seconds

视频时长（秒）：4、6、8

Example:

6

​
size
enum<string>
default:1280x720

分辨率

Available options:
1280x720,
720x1280,
1920x1080,
1080x1920
Example:

"1280x720"

​
input_reference
string[]

参考图 URL 数组（1-3 张）

Example:
["https://example.com/image.jpg"]

Response

任务创建成功

​
id
string

任务 ID

Example:

"video_abc123"

​
object
enum<string>
Available options:
video
Example:

"video"

​
created_at
integer

创建时间戳

Example:

1761234567

​
completed_at
integer

完成时间戳

​
status
enum<string>

任务状态

Available options:
queued,
in_progress,
completed,
failed
Example:

"queued"

​
model
string

模型名称

Example:

"veo-3.1-fast-generate-preview"

​
prompt
string

提示词

​
progress
number

进度（0-100）

Example:

0

​
seconds
integer

视频时长

Example:

6

​
size
string

分辨率

Example:

"1280x720"

​
video_url
string

视频直链（完成后返回）

​
error
object