After completion, `metadata.content_url` provides the directly accessible video address; it can also be downloaded using the content interface below.

Response (failed)

{
  "id": "task_12345",
  "object": "video",
  "status": "failed",
  "error": { "message": "Failure reason" }
}

3. Download video content

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


Returns 409 Conflict if task is not completed (Still in queue/generating).

Supports segmented download/drag-and-drop playback using the  request header.

Returns . 


Full example
JavaScript (fetch + polling)
const BASE = process.env.KOZEAI_BASE_URL;
const KEY = process.env.KOZEAI_API_KEY;
const headers = { Authorization: `Bearer ${KEY}` };

// 1. Submit task
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. Poll until completed
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. Get the video address
console.log('Video address:', done.metadata?.content_url
  || `${BASE}/v1/videos/${taskId}/content`);

Python (requests + polling)
import os, time, requests

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

# 1. Submit task
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. Polling
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. Download
mp4 = requests.get(f"{BASE}/v1/videos/{task_id}/content", headers=headers)
with open("result.mp4", "wb") as f: f.write(mp4.content)


Called in the chat completion interface (compatible usage)

The video model can also be called via /v1/chat/completions, facilitating the reuse of chat clients.
 When making a request, simply pass the video model name in `model`, and the system will automatically convert it into a video task:

curl $KOZEAI_BASE_URL/v1/chat/completions
 \
-H Authorization: Bearer $KOZEAI_API_KEY \
-H Content-Type: application/json \
-d {
Model: } `
returns "video-ds-2.0
,

"messages: [{"role: "user, "content: "a cat running in the sunlight, cinematic, 9:16}]

}

Returns chat completion
 The format is `message.content`, which contains the task status and a link `/v1/videos/{task_id}`. This link will play the video once it completes. The chat lobby page uses this method.



Both entry points (/v1/videos/generations and /v1/chat/completions) share the same task system and do not conflict with each other. For direct integration, it is recommended to use the standard `/v1/videos/*` interface.
 






Error Code







Status Code

Meaning









401

Token missing, expired, or invalid




403

Insufficient balance, or the current group does not have permission for this model




404

Task ID Does not exist, or does not belong to the current user; or the model is not configured.





409

Video content is not ready (task is still queuing/generating)



429

Triggering rate limit



502

Upstream supplier failed or returned invalid result