Documentação da API de vídeo

A API é assíncrona: você envia o pedido, recebe um id e consulta pelo id até o vídeo ficar pronto. Aceita as proporções 16:9 (horizontal), 9:16 (vertical), 1:1, 4:3, 3:4 e 21:9, com imagens de referência opcionais.

1. Autenticação

A API key da sua conta fica em Minha conta. Todo request (exceto /health e os links /preview e /download) precisa do header:

Authorization: Bearer <API_KEY>

Sem header ou com uma key inválida, o servidor responde 401 {"error":"unauthorized"}.

2. Fluxo de processamento

O tempo de geração depende do modelo. Se o vídeo não chegar em 4 minutos (padrão do servidor), o job passa para failed e o valor é reembolsado.

POST /v1/videos        →  202 {"id": "...", "status": "queued"}
        │
        ▼   (consulte a cada ~5 segundos)
GET  /v1/videos/{id}   →  status: queued → generating → done | failed
        │
        ▼
 done: use o campo "url" para tocar ou baixar o vídeo (.mp4)

3. Criar vídeo

Campos do body (JSON)

Cada item de images

Com 1 imagem, ela é usada como primeiro quadro e referência principal. Com várias, todas viram referência de uma única cena contínua; descreva no prompt o papel de cada uma (ex.: "a pessoa da imagem 1 segura o produto da imagem 2").

Com imagem de referência, o vídeo pode manter a proporção da imagem em vez do aspect_ratio. Para garantir o formato, envie a imagem já recortada na mesma proporção do aspect_ratio pedido.

Resposta de sucesso — 202 Accepted

{ "id": "5f3e9c2f-4ac4-455f-ab73-03c07e8f8079", "status": "queued", "balance": 900 }

Erros na criação

3b. Criar imagem

A API também gera imagens. Mesma key, mesma fila e mesmo fluxo assíncrono dos vídeos; o resultado é um PNG, fica pronto em cerca de 1 minuto e custa price_per_image créditos (padrão 20, bem menos que um vídeo). GET /v1/key mostra price_per_image e remaining_images.

duration_seconds, video e video_url não se aplicam a imagens e devolvem 400.

{ "id": "9b1c5e30-2d4f-4a0e-9c1d-3f2e8a7b6c5d", "kind": "image", "status": "queued", "balance": 980 }

Acompanhe em __BASE__/v1/images/{id} (ou em /v1/videos/{id}: o id é o mesmo). A resposta tem o formato de 4. Ver o resultado, com "kind": "image", "media_type": "image", duration_seconds nulo e url/download_url em /v1/images/{id}/preview e /download. GET /v1/images lista só as imagens; GET /v1/videos?kind=all lista vídeos e imagens juntos. Sem saldo: 402 com price_per_image.

curl -X POST "__BASE__/v1/images" -H "Authorization: Bearer $VIDEOAPI_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"pôster minimalista de um farol numa tempestade","aspect_ratio":"9:16"}'
curl "__BASE__/v1/images/<id>" -H "Authorization: Bearer $VIDEOAPI_KEY"

4. Ver o resultado

Resposta — 200 OK

{
  "id": "5f3e9c2f-4ac4-455f-ab73-03c07e8f8079",
  "kind": "video",
  "status": "done",
  "prompt": "a dog running on the beach",
  "aspect_ratio": "9:16",
  "requested_seconds": 10,
  "duration_seconds": 8,
  "url": "__BASE__/v1/videos/5f3e9c2f-4ac4-455f-ab73-03c07e8f8079/preview",
  "source": "local",
  "download_url": "__BASE__/v1/videos/5f3e9c2f-4ac4-455f-ab73-03c07e8f8079/download",
  "preview_url": "__BASE__/v1/videos/5f3e9c2f-4ac4-455f-ab73-03c07e8f8079/preview",
  "media_type": "video",
  "expires_at": "2026-10-21T14:54:12.301Z",
  "error": null,
  "created_at": "2026-10-20T14:52:54.877Z",
  "finished_at": "2026-10-20T14:54:12.301Z"
}

Campos da resposta

Motivos comuns de failed

Erros de conexão com o provedor também aparecem em error. Em todos os casos de failed o valor volta 100% para o saldo.

5. Exemplos completos

# Criar vídeo
curl -X POST "__BASE__/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a dog running on the beach","aspect_ratio":"9:16"}'

# Ver resultado
curl "__BASE__/v1/videos/<id>" \
  -H "Authorization: Bearer $API_KEY"

// Node.js 18+ (ES module) ou navegador
import fs from 'node:fs';

const BASE = '__BASE__';
const headers = { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' };

// Imagem de referência (opcional): lida do disco e codificada em base64
const image = {
  mime_type: 'image/png',
  data_base64: fs.readFileSync('input.png').toString('base64'),
  filename: 'input.png',
};

const { id } = await (await fetch(`${BASE}/v1/videos`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ prompt: 'make the picture come alive', aspect_ratio: '16:9', images: [image] }),
})).json();

let job;
do {
  await new Promise(r => setTimeout(r, 5000));
  job = await (await fetch(`${BASE}/v1/videos/${id}`, { headers })).json();
} while (job.status === 'queued' || job.status === 'generating');

if (job.status === 'done') console.log('Vídeo:', job.url);
else console.error('Erro:', job.error);

import base64, time, requests

BASE = "__BASE__"
H = {"Authorization": f"Bearer {API_KEY}"}

with open("input.png", "rb") as f:
    image = {"mime_type": "image/png", "data_base64": base64.b64encode(f.read()).decode()}

r = requests.post(f"{BASE}/v1/videos", headers=H, json={
    "prompt": "make the picture come alive",
    "aspect_ratio": "9:16",
    "images": [image],       # remova esta linha se não tiver imagem
})
job_id = r.json()["id"]

while True:
    time.sleep(5)
    job = requests.get(f"{BASE}/v1/videos/{job_id}", headers=H).json()
    if job["status"] in ("done", "failed"):
        break

print(job["url"] if job["status"] == "done" else job["error"])

5b. MCP: use a VIDEOAPI de dentro do seu agente

A API também fala Model Context Protocol (transporte Streamable HTTP) em __BASE__/mcp. Autentique com a sua API key no header Authorization: Bearer <API_KEY> ou, para clientes que não enviam headers, na própria URL: __BASE__/mcp/<API_KEY> (trate essa URL como segredo).

Ferramentas expostas: create_video, create_image, wait_for_video, get_video, list_videos e get_balance. Em Minha conta → MCP há o passo a passo para Claude, Claude Code, ChatGPT, Cursor, Codex, VS Code, Gemini e Hermes.

claude mcp add --transport http videoapi __BASE__/mcp --header "Authorization: Bearer $VIDEOAPI_KEY"

6. Notas de operação

• Links expiram: veja expires_at. A cópia local fica 24 h; depois disso /preview e /download respondem 410 {"error":"video expired"} e o link não é reemitido. Guarde o .mp4 no seu armazenamento antes.
• Link direto para .mp4: pode ir direto em <video src="..."> ou ser baixado.
• Polling: a cada 5 segundos é o ideal; não precisa ser mais rápido.
• Fila: os jobs são processados em ordem de chegada. Cada key pode ter até 8 jobs aguardando (padrão do servidor) (queued + generating); acima disso a criação responde 429.
• Privacidade: as imagens de referência ficam só em memória e são descartadas quando o job termina.
• Sem webhook: o resultado é obtido por polling em GET /v1/videos/{id}, sem precisar abrir uma porta pública para callbacks.
• CORS: os endpoints /v1 aceitam chamadas de qualquer origem, então dá para usar direto do navegador.

7. Saúde do servidor

Verificação rápida de que a API está no ar (não pede API key):

{"ok": true}

8. Saldo e histórico

Endpoints só de leitura, sempre limitados à key enviada no header. São os mesmos dados da página Minha conta.

Saldo rápido

{ "balance": 900, "tier": 1, "tier_name": "Padrão", "plan_type": "prepaid" }

Informações da key e totais

{
  "api_key_masked": "sk-7047…b0ed70",
  "status": "active",
  "tier": 1,
  "tier_name": "Padrão",
  "plan_type": "prepaid",
  "balance": 900,
  "price_per_video": 100,
  "remaining_videos": 9,
  "expires_at": null,
  "created_at": "2026-10-01T09:00:00.000Z",
  "last_used_at": "2026-10-15T20:39:12.000Z",
  "totals": {
    "deposited": 1000, "spent": 100, "holding": 0, "refunded": 100,
    "jobs": 3, "done": 1, "failed": 1, "pending": 1
  }
}

deposited, spent, holding (reservado por jobs em andamento) e refunded estão em créditos; jobs, done, failed e pending são contagens.

Jobs da key

status (opcional): done, failed, queued, generating ou pending (= queued + generating). limit: 1–500, padrão 100. Mais recentes primeiro; cada item tem a estrutura da seção 4 mais cost e refunded.

{ "data": [ { "id": "5f3e9c2f-…", "status": "done", "cost": 100, "refunded": false, "url": "…", … } ] }