Obter status do vídeo


GET https://api.ofox.ai/v1/videos/{id}

Consulte o status e o resultado de uma tarefa. Depois de criar uma tarefa, faça polling neste endpoint até status chegar a um estado terminal — completed, failed, cancelled ou expired.

Terminal


curl https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718 \
  -H "Authorization: Bearer $OFOX_API_KEY"

Limite de taxa

Este endpoint tem limite de taxa por API key (padrão 5 req/s com burst de 20). Requisições acima do limite retornam 429 rate_limited com o header Retry-After: 1. Criação (POST) e cancelamento (DELETE) não estão sujeitos a este limite.

Não faça polling mais de uma vez por segundo; ou forneça um callback_url ao criar a tarefa para receber um webhook em vez de fazer polling.

Resposta

Concluída


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "completed",
  "model": "google/veo-3.1",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.ai/videos/vgen_xxx.mp4?sig=..."],
  "usage": {
    "video_seconds": 5,
    "video_cost": "0.4000000000"
  },
  "created_at": 1776211362,
  "updated_at": 1776211400
}

Um timeout é relatado como status: "failed" com error.code definido como expired. Para a lista completa de códigos de erro, veja Códigos de erro.

O objeto Video

Campo	Tipo	Descrição
`id`	string	Identificador único da tarefa (UUID)
`status`	enum	Veja Máquina de estados
`model`	string	Slug do modelo
`prompt`	string	Prompt original
`unsigned_urls`	string[]	Presente quando `completed`. URL original do vídeo no upstream (temporária, pode expirar em 24h)
`mirror_urls`	string[]	Presente quando `completed` e o provedor do modelo tem espelhamento CDN ativado. URL assinada persistente — veja URLs de vídeo
`error`	object	Presente quando `failed`: `{code, message}`
`usage`	object	Presente quando `completed`: `{video_seconds, video_cost}`. `video_seconds` são os segundos cobrados (inclui segundos de input v2v); `video_cost` é a cobrança real no preço do nível da plataforma, uma string decimal fixa com 10 casas (evita perda de precisão)
`created_at` / `updated_at`	integer	Segundos Unix

Máquina de estados

Sete estados, baseados na nomenclatura do OpenRouter e estendidos com cancelled / expired.

Status	Terminal	Descrição
`pending`	—	Aceita, ainda não enviada ao upstream
`queued`	—	Enviada ao upstream, aguardando na fila
`in_progress`	—	Gerando no upstream
`completed`	✓	Sucesso, URLs de vídeo disponíveis
`failed`	✓	Falhou (incluindo timeout, `error.code=expired`)
`cancelled`	✓	Cancelada
`expired`	✓	Expirada

Transições: pending → queued → in_progress → completed é o caminho de sucesso. Qualquer estado não terminal pode mover para failed, cancelled ou expired.

URLs de vídeo

Uma tarefa bem-sucedida pode retornar dois conjuntos de URLs, dependendo de o provedor do modelo ter espelhamento CDN ativado.

Campo	Fonte	Características
`unsigned_urls`	Endereço original do provedor upstream	Temporária — sempre presente · pode expirar em 24h · não assinada
`mirror_urls`	Espelho CDN da ofox	Persistente — apenas para provedores com CDN ativada · assinada a cada requisição · tem TTL

Prefira mirror_urls (persistentes e estáveis). Quando um modelo retorna apenas unsigned_urls, baixe ou hospede novamente o arquivo rapidamente antes que o endereço temporário do upstream expire.