視訊產生 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_1KOZEAI_BASE_URL/v1/videos/task_12445;
  -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_1">$KOZEAI_BASE_URL/v1/videos/task_1&D45
  -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/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 = > class="hljs-number">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).jheaders(span).
    if data["status"] == "completed":
        break
    if data["status"] == "failed":
        raise RuntimeError(data.get("error", {}).get("message", &hl34;
    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": "user", "一隻貓在陽光下奔跑，電影感，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	上游供應商失敗或傳回無效結果