Parâmetros da Requisição

Diferentes modelos upstream podem suportar parâmetros diferentes. Os parâmetros não listados serão repassados de acordo com o protocolo upstream.

Vídeo gerado por imagem (com imagens de referência)

Passe o array images para gerar um vídeo com base nas imagens de referência:

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 o estilo da imagem de referência e crie um vídeo de produto suave",
"seconds": 15,
"aspect_ratio": "9:16",

"images": [ 
images aceita URLs de imagens ou base64.

videos / audios são materiais de referência opcionais. 

Ao ligar através da interface de autocompletar do chat (veja no final do artigo), basta anexar a imagem à mensagem; o sistema a converterá automaticamente no parâmetro images. 

Resposta (envio bem-sucedido)
{
"id": "task_12345",
"task_id": "task_12345",
"object": "video",
"model": status Valores: queued (na fila), in_progress (em andamento), completed (concluído), failed (falhou). 




2. Status da Tarefa de Sondagem

Use o id retornado pelo envio para sondar, com um intervalo recomendado de 3 a 5 segundos.

curl"$KOZEAI_BASE_URL/v1/videos/task_12345" \

-H "Authorization: Bearer $KOZEAI_API_KEY"

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

Response (Complete)
{
"id": "task_12345",
"object": "video",
"model": "video-ds-2.0",
"status": "completed",
"progress": 100,

"created_at": 1751000000,


Após a conclusão, `metadata.content_url` fornece o endereço do vídeo diretamente acessível; ele também pode ser baixado usando a interface de conteúdo abaixo. 
Resposta (falhou)
{
"id": "task_12345",
"object": "video",
"status": "failed",
"error": { "message": "Motivo da falha" }
}


3. Baixar conteúdo de vídeo
curl -L "$KOZEAI_BASE_URL/v1/videos/task_12345/content" \

-H "Authorization: Bearer $KOZEAI_API_KEY" \

-o result.mp4


Retorna 409 Conflict se a tarefa não estiver concluída (Ainda na fila/gerando).

Suporta download segmentado/reprodução por arrastar e soltar usando o cabeçalho de solicitação .

Retorna . 


Exemplo completo
JavaScript (busca + polling)
const BASE = process.env.KOZEAI_BASE_URL;
const KEY = process.env.KOZEAI_API_KEY;

const headers = { Authorization: `Bearer ${KEY}` };

// 1. Enviar tarefa
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: 'Um vídeo comercial suave de um frasco de perfume em vidro',

seconds: 15,

aspect_ratio: '9:16',
}),
});
const task = await submit.json();
const taskId = task.id;

// 2. Sondar até a conclusão
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. Obter o endereço do vídeo
console.log('Endereço do vídeo:', done.metadata?.content_url

|| `${BASE}/v1/videos/${taskId}/content`);

Python (requisições + polling)
import os, time, requests

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

# 1. Enviar tarefa
resp = requests.post(
f"{BASE}/v1/videos/generations",
headers=headers,
json={
"model": "video-ds-2.0",
"prompt": "Um vídeo cinematográfico de 9:16 de um gato correndo por um local quente luz solar,
segundos: 15,
proporção de aspecto: 9:16,
},
)
task_id = resp.json()[id]

# 2. Sondagem
while True:

data = requests.get(f{BASE}/v1/videos/{task_id}, headers=headers).json()
if data["status"] == "completed":

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)


Chamado na interface de autocompletar do chat (uso compatível)

O modelo de vídeo também pode ser chamado via /v1/chat/completions, facilitando a reutilização de clientes de chat.
 Ao fazer uma requisição, basta passar o nome do modelo de vídeo em `model`, e o sistema o converterá automaticamente em uma tarefa de vídeo:

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: "um gato correndo na luz do sol, cinematográfico, 9:16}]

}

Retorna a conclusão do chat
 O formato é `message.content`, que contém o status da tarefa e um link `/v1/videos/{task_id}`. Este link reproduzirá o vídeo assim que a tarefa for concluída. A página do lobby do chat usa este método.



Ambos os pontos de entrada (/v1/videos/generations e /v1/chat/completions) compartilham o mesmo sistema de tarefas e não entram em conflito entre si. Para integração direta, recomenda-se usar o padrão. `/v1/videos/*` interface.






Código de Erro







Código de Status

Significado








401

Token ausente, expirado ou inválido




403

Saldo insuficiente ou o grupo atual não tem permissão para este modelo





404

O ID da tarefa não existe ou não pertence ao usuário atual; ou o modelo não é Configurado.




409

O conteúdo de vídeo não está pronto (a tarefa ainda está na fila/gerando)


429

Acionando o limite de taxa


502

O fornecedor upstream falhou ou retornou um resultado inválido