Criar vídeo

Envie uma tarefa de geração de vídeo. A requisição retorna 202 Accepted imediatamente com um id da tarefa e uma URL de polling — a geração roda de forma assíncrona. Consulte a tarefa por polling ou receba um webhook, depois leia o resultado com Obter status do vídeo.


POST https://api.ofox.ai/v1/videos

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	✅	Slug do modelo, por exemplo `google/veo-3.1` ou `bytedance/seedance-2.0`
`prompt`	string	✅	Descrição textual do vídeo
`duration`	integer	—	Duração do vídeo em segundos
`resolution`	string	—	`480p` / `720p` / `1080p` / `1K` / `2K` / `4K`
`aspect_ratio`	string	—	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9` / `9:21`
`size`	string	—	Pixels exatos `WIDTHxHEIGHT` (por exemplo `1280x720`), uma alternativa a `resolution` + `aspect_ratio`
`frame_images`	array	—	Controle de frames (imagem para vídeo / primeiro e último frame). Presente ⇒ tratado como imagem para vídeo. Veja abaixo
`input_references`	array	—	Guia de assunto / estilo (referência para vídeo), não âncoras precisas de frame. Veja abaixo
`generate_audio`	boolean	—	Padrão `true` em modelos que suportam saída de áudio
`seed`	integer	—	Seed de geração determinística (não garantida em todos os provedores)
`callback_url`	string	—	URL de webhook de estado terminal, deve usar HTTPS (veja Webhooks)
`provider`	object	—	Repasse específico do provedor, veja Repasse para provider

Elemento de `frame_images[]`

Cada elemento fixa um frame da saída. frame_type é first_frame ou last_frame.


{
  "type": "image_url",
  "image_url": { "url": "https://example.com/first.jpg" },
  "frame_type": "first_frame"
}

Elemento de `input_references[]`

Envie referências de imagem / áudio / vídeo por type — elas guiam assunto, estilo e consistência, não âncoras precisas de frame:


{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }

Mídia	`type`	Máximo	Outras restrições
Imagem	`image_url`	≤ 9	—
Áudio	`audio_url`	≤ 3	≤ 15s por clipe
Vídeo	`video_url`	≤ 1	—

Exceder qualquer limite retorna 400 too_many_references (veja Erros).

frame_images e input_references são mutuamente exclusivos — uma única requisição usa um ou outro, nunca ambos. Enviar ambos retorna 400 references_conflict.

Modo de geração (implícito)

Não há campo gen_mode. O modo é inferido a partir dos inputs enviados:

Modo	Detectado quando
`text2video`	Nem `frame_images` nem `input_references`
`img2video`	`frame_images` com um `first_frame`
`img2video_end`	`frame_images` com `first_frame` + `last_frame`
`imgref2video`	`input_references`, apenas imagens
`mixref2video`	`input_references` misturando imagem / áudio / vídeo

Resposta

202 Accepted — a tarefa é aceita com status: "pending" e um polling_url:


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

Consulte polling_url por polling (ou aguarde um webhook) até a tarefa chegar a um estado terminal — veja Obter status do vídeo.

Exemplos de requisição

Um único esquema de /v1/videos cobre todos os modos de geração; o modo é escolhido implicitamente a partir dos seus inputs. Cada exemplo abaixo roda como está.

Texto para vídeo

Sem frame_images / input_references → texto para vídeo.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

Imagem para vídeo

frame_images com um first_frame → animar a partir de uma imagem inicial.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Make the dog in the frame start running",
    "duration": 5,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/dog.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

Primeiro e último frame

frame_images com first_frame + last_frame → interpolar entre dois frames.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Smoothly transition between the two frames",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/start.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/end.jpg" },   "frame_type": "last_frame" }
    ]
  }'

Referência de imagem

input_references apenas com imagens (guia assunto / estilo, não âncoras de frame) — até 9.

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "This character skiing down a snowy mountain",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/style-ref.jpg" } }
    ]
  }'

Referência mista

input_references misturando imagem / áudio / vídeo (imagem ≤ 9 · áudio ≤ 3, ≤ 15s cada · vídeo ≤ 1).

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Have the character speak in the tone of this voice clip, in the style of this reference video",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } },
      { "type": "video_url", "video_url": { "url": "https://example.com/style-ref.mp4" } }
    ]
  }'

Opções combináveis

Os campos abaixo são ortogonais ao modo de geração — adicione qualquer um deles a qualquer corpo de requisição acima.

Webhook (callback_url)

Receba um POST no seu endpoint quando a tarefa chegar a um estado terminal, em vez de fazer polling.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url deve usar HTTPS. Veja Webhooks para o payload e a assinatura.

Repasse para provider

Repasse parâmetros específicos do provedor (por exemplo watermark) por provider.options.<slug>.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": { "dashscope": { "watermark": false } }
  }
}

Tamanho exato em pixels

Use size para pixels exatos no lugar de resolution + aspect_ratio.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "size": "1280x720"
}

Áudio + seed

Ative a saída de áudio e fixe uma seed determinística.


{
  "model": "google/veo-3.1",
  "prompt": "...",
  "generate_audio": true,
  "seed": 42
}

Repasse para provider

Parâmetros específicos do provedor passam por provider.options.<slug> — apenas o provedor correspondente os recebe. Parâmetros como watermark não são suportados por todos os modelos, então ficam no repasse para provider em vez de campos de nível superior (isso segue a convenção de repasse para provider do OpenRouter). As opções de repasse aceitas por um modelo dependem das capacidades do modelo.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": {
      "dashscope": { "watermark": false, "audio_setting": "..." }
    }
  }
}

Criar vídeo

Parâmetros da requisição

Elemento de frame_images[]

Elemento de input_references[]

Modo de geração (implícito)

Resposta

Exemplos de requisição

Texto para vídeo

Imagem para vídeo

Primeiro e último frame

Referência de imagem

Referência mista

Opções combináveis

Webhook (callback_url)

Repasse para provider

Tamanho exato em pixels

Áudio + seed

Repasse para provider

Elemento de `frame_images[]`

Elemento de `input_references[]`