视频生成 API 调用文档

kozeai 提供与 OpenAI Sora 兼容的视频生成接口，采用异步任务模式：先提交任务拿到 task_id，再轮询任务状态，完成后下载视频内容。

鉴权

所有请求通过 Authorization: Bearer <API_TOKEN> 鉴权。在控制台创建 API 令牌后使用。

export KOZEAI_API_KEY="sk-your-token"
export KOZEAI_BASE_URL="https://api.kozeai.com"

接口总览

方法	路径	用途
POST	/v1/videos/generations	创建视频任务
GET	/v1/videos/{task_id}	查询任务状态
GET	/v1/videos/{task_id}/content	在线播放或下载 mp4

任务 ID 形如 task_12345，由提交接口返回，仅属于当前用户。

---

1. 创建视频任务

curl "$KOZEAI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0",
    "prompt": "A cinematic 9:16 video of a cat running through warm sunlight",
    "seconds": 15,
    "aspect_ratio": "9:16"
  }'

请求参数

参数	类型	必填	说明
model	string	是	视频模型名称，如 video-ds-2.0
prompt	string	是	视频内容描述
seconds	integer	否	视频时长（秒），按上游模型支持范围
aspect_ratio	string	否	画幅比例，常用 9:16、16:9、1:1
images	array	否	参考图片 URL 或 base64
videos	array	否	参考视频 URL
audios	array	否	参考音频 URL

不同上游模型支持的参数可能不同，未列出的参数会按上游协议透传。

图生视频（带参考图片）

传入 images 数组即可基于参考图片生成视频：

curl "$KOZEAI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0",
    "prompt": "Use the reference image style and create a smooth product video",
    "seconds": 15,
    "aspect_ratio": "9:16",
    "images": ["https://example.com/input.png"],
    "videos": ["https://example.com/input.mp4"],
    "audios": ["https://example.com/input.mp3"]
  }'

• images 支持图片 URL 或 base64。
• videos / audios 为可选参考素材。
• 通过聊天补全接口（见文末）调用时，直接在消息中附带图片即可，系统会自动转换为 images 参数。

响应（提交成功）

{
  "id": "task_12345",
  "task_id": "task_12345",
  "object": "video",
  "model": "video-ds-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1751000000
}

status 取值：queued（排队）、in_progress（生成中）、completed（完成）、failed（失败）。

---

2. 轮询任务状态

用提交返回的 id 轮询，建议间隔 3~5 秒。

curl "$KOZEAI_BASE_URL/v1/videos/task_12345" \
  -H "Authorization: Bearer $KOZEAI_API_KEY"

响应（生成中）

{
  "id": "task_12345",
  "object": "video",
  "model": "video-ds-2.0",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1751000000
}

响应（完成）

{
  "id": "task_12345",
  "object": "video",
  "model": "video-ds-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1751000000,
  "completed_at": 1751000180,
  "metadata": {
    "content_url": "https://your-kozeai-domain/v1/videos/task_12345/content/public?sig=..."
  }
}

完成后 metadata.content_url 提供可直接访问的视频地址；也可调用下方的内容接口下载。

响应（失败）

{
  "id": "task_12345",
  "object": "video",
  "status": "failed",
  "error": { "message": "失败原因" }
}

---

3. 下载视频内容

curl -L "$KOZEAI_BASE_URL/v1/videos/task_12345/content" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -o result.mp4

• 任务未完成时返回 409 Conflict（仍在排队/生成中）。
• 支持 Range 请求头做分段下载/拖动播放。
• 返回 Content-Type: video/mp4。

---

完整示例

JavaScript（fetch + 轮询）

const BASE = process.env.KOZEAI_BASE_URL;
const KEY = process.env.KOZEAI_API_KEY;
const headers = { Authorization: `Bearer ${KEY}` };

// 1. 提交任务
const submit = await fetch(`${BASE}/v1/videos/generations`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'video-ds-2.0',
    prompt: 'A smooth commercial video of a perfume bottle on glass',
    seconds: 15,
    aspect_ratio: '9:16',
  }),
});
const task = await submit.json();
const taskId = task.id;

// 2. 轮询直到完成
async function poll() {
  while (true) {
    const res = await fetch(`${BASE}/v1/videos/${taskId}`, { headers });
    const data = await res.json();
    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error(data.error?.message || 'failed');
    await new Promise((r) => setTimeout(r, 5000));
  }
}
const done = await poll();

// 3. 取视频地址
console.log('视频地址:', done.metadata?.content_url
  || `${BASE}/v1/videos/${taskId}/content`);

Python（requests + 轮询）

import os, time, requests

BASE = os.environ["KOZEAI_BASE_URL"]
KEY = os.environ["KOZEAI_API_KEY"]
headers = {"Authorization": f"Bearer {KEY}"}

# 1. 提交任务
resp = requests.post(
    f"{BASE}/v1/videos/generations",
    headers=headers,
    json={
        "model": "video-ds-2.0",
        "prompt": "A cinematic 9:16 video of a cat running through warm sunlight",
        "seconds": 15,
        "aspect_ratio": "9:16",
    },
)
task_id = resp.json()["id"]

# 2. 轮询
while True:
    data = requests.get(f"{BASE}/v1/videos/{task_id}", headers=headers).json()
    if data["status"] == "completed":
        break
    if data["status"] == "failed":
        raise RuntimeError(data.get("error", {}).get("message", "failed"))
    time.sleep(5)

# 3. 下载
mp4 = requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=headers)
with open("result.mp4", "wb") as f:
    f.write(mp4.content)

---

在聊天补全接口中调用（兼容用法）

视频模型也可通过 /v1/chat/completions 调用，便于复用聊天客户端。请求时 model 传视频模型名即可，系统会自动转为视频任务：

curl "$KOZEAI_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $KOZEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0",
    "messages": [{"role": "user", "content": "一只猫在阳光下奔跑，电影感，9:16"}]
  }'

返回的是 chat completion 格式，message.content 中包含任务状态及 /v1/videos/{task_id} 链接；视频完成后该链接即可播放。聊天大厅页面即采用此方式。

两种入口（/v1/videos/generations 与 /v1/chat/completions）共用同一套任务系统，互不冲突。直接对接建议用标准的 /v1/videos/* 接口。

---

错误码

状态码	含义
401	令牌缺失、过期或无效
403	余额不足，或当前分组无该模型权限
404	任务 ID 不存在，或不属于当前用户；或模型未配置
409	视频内容尚未就绪（任务仍在排队/生成中）
429	触发限速
502	上游供应商失败或返回无效结果