Skip to Content
Referência da APIGeração de vídeoCriar vídeo

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âmetroTipoObrigatórioDescrição
modelstring✅Slug do modelo, por exemplo bytedance/seedance-2.5 ou bytedance/seedance-2.0
promptstring✅Descrição textual do vídeo
durationinteger—Duração do vídeo em segundos
resolutionstring—480p / 720p / 1080p / 1K / 2K / 4K
aspect_ratiostring—16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 9:21
sizestring—Pixels exatos WIDTHxHEIGHT (por exemplo 1280x720), uma alternativa a resolution + aspect_ratio
frame_imagesarray—Controle de frames (imagem para vídeo / primeiro e último frame). Presente ⇒ tratado como imagem para vídeo. Veja abaixo
input_referencesarray—Guia de assunto / estilo (referência para vídeo), não âncoras precisas de frame. Veja abaixo
real_personboolean—Padrão false. Use true para pré-processar referências de pessoas reais antes da geração; exige pelo menos uma referência de imagem
generate_audioboolean—Padrão true em modelos que suportam saída de áudio
seedinteger—Seed de geração determinística (não garantida em todos os provedores)
callback_urlstring—URL de webhook de estado terminal, deve usar HTTPS (veja Webhooks)
providerobject—type fixa o provedor, options repassa parâmetros específicos do provedor. Veja Roteamento de provedores

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ídiatypeMáximoOutras restrições
Imagemimage_url≤ 9—
Áudioaudio_url≤ 3≤ 15s por clipe
Vídeovideo_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.

real_person: Imagens de referência de pessoas reais

Consulte Imagens de referência de pessoas reais para ver o fluxo de uma etapa da Ofox, a comparação com o cadastro de ativos no Seedance e orientações práticas de nova tentativa.

Defina o campo de nível superior real_person como true quando uma imagem de referência contiver uma pessoa real identificável. A Ofox aplica um pré-processamento que preserva a privacidade a cada imagem do campo de referência escolhido antes de enviar a solicitação de geração. O padrão é false, portanto as solicitações existentes não mudam.

{
  "model": "bytedance/seedance-2.0",
  "prompt": "A pessoa caminha por um mercado noturno cinematográfico",
  "real_person": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" }
    }
  ]
}

Você pode usar real_person com imagens em frame_images ou input_references; os dois campos continuam mutuamente exclusivos. É necessária pelo menos uma referência de imagem; caso contrário, a API retorna 400 invalid_request.

O pré-processamento pode reduzir falsos bloqueios das verificações anti-deepfake do provedor upstream, mas não contorna a política de conteúdo nem garante a aceitação. O provedor ainda pode rejeitar a solicitação; uma tarefa rejeitada não é cobrada. Corrija a entrada ou tente novamente. Veja erros de pré-processamento de real_person.

Modo de geração (implícito)

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

ModoDetectado quando
text2videoNem frame_images nem input_references
img2videoframe_images com um first_frame
img2video_endframe_images com first_frame + last_frame
imgref2videoinput_references, apenas imagens
mixref2videoinput_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á.

Sem frame_images / input_references → texto para vídeo.

Terminal
# Opcional: fixar um provedor. Se omitir, a plataforma faz o roteamento
# "provider": { "type": "byteplus" }
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.5",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

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.

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

{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

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

Last updated on
Modelos de vídeoPessoas reais