Geração de vídeos
Gere um vídeo com um Model ID compatível: crie uma tarefa, consulte o status e baixe o arquivo.
A geração de vídeos é assíncrona: uma solicitação cria uma tarefa, e o vídeo só fica disponível quando a tarefa termina com sucesso. Antes de começar, confirme na página do modelo as resoluções, durações e preços por resolução compatíveis.
Endpoints da solicitação
A geração de vídeos usa um endpoint para criar a tarefa e três para acompanhá-la:
| Método e caminho | Uso |
|---|---|
POST /v1/videos | Criar uma tarefa de geração de vídeo |
GET /v1/videos/{id} | Consultar o status da tarefa |
GET /v1/videos/{id}/content | Baixar o vídeo pronto |
DELETE /v1/videos/{id} | Excluir a tarefa, quando a interface do modelo permitir |
Todos os caminhos usam https://api.vergora.ai e o mesmo cabeçalho Authorization: Bearer YOUR_VERGORA_API_KEY das demais solicitações. Somente a criação de tarefas é cobrada.
Exemplo de solicitação
POST https://api.vergora.ai/v1/videos{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "Um barco de papel descendo uma rua chuvosa, com a câmera se aproximando devagar",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}A resposta de criação traz o id da tarefa e o status inicial. Guarde o id: ele é necessário em todas as solicitações seguintes.
Modelos com a interface de vídeo compatível com a OpenAI usam seconds e size (por exemplo, "8" e "1280x720") em vez de duration, resolution e ratio. A aba API de cada página de modelo mostra uma solicitação no formato correto.
Campos da solicitação
| Campo | Descrição |
|---|---|
model | Um Model ID para geração de vídeos |
prompt | Assunto, ação, cena e movimento de câmera |
content | Entrada estruturada no lugar de prompt, se aceita |
input_reference | URL de uma imagem para o quadro inicial |
duration | Duração do vídeo em segundos |
resolution | Resolução de saída, como 720p ou 1080p |
ratio | Proporção da tela, como 16:9 (ou aspect_ratio) |
| Outros parâmetros | Use somente se o modelo for compatível |
content pode trazer texto, uma imagem de referência ou um vídeo de entrada. Outros parâmetros incluem seed, watermark, generate_audio, camera_fixed e service_tier; envie-os somente para modelos compatíveis. Seedance 2.0 / 2.5 não aceitam seed nem camera_fixed; o gateway os remove para esses modelos. Wan 2.5 / 2.6 e W3.0 usam audio (booleano, ativado por padrão) em vez de generate_audio.
Envie o corpo da solicitação em JSON. Para usar um vídeo de entrada, informe um link público ou a chave de um arquivo enviado (veja Imagens e vídeos de referência abaixo); se for um link, precisa ser uma URL pública http ou https (por exemplo, em um item de content do tipo video_url); não é possível usar URIs data:. Solicitações com vídeo de entrada são cobradas pela tarifa com vídeo de entrada do modelo.
Imagens e vídeos de referência
Uma imagem ou um vídeo de referência pode ser informado de qualquer uma destas formas. O mesmo campo aceita todas, e o gateway as distingue:
| Forma | Exemplo | Observações |
|---|---|---|
| Link público | https://cdn.example.com/clip.mp4 | O provedor do modelo faz o download, então o link precisa ser acessível pela internet |
| Arquivo enviado | uploads/u42/20261112/0123…cdef.mp4 | A chave retornada por POST /v1/uploads (veja abaixo). Ela é trocada por um link temporário antes de a solicitação chegar ao provedor |
| Dados embutidos | data:image/png;base64,… | Somente imagens. Vídeos não são aceitos embutidos |
Coloque a referência onde a interface do modelo espera: input_reference para uma imagem de quadro inicial, ou itens de content dos tipos image_url e video_url:
{
"model": "YOUR_VIDEO_MODEL_ID",
"content": [
{
"type": "text",
"text": "A mesma cena à noite, com a câmera se aproximando devagar"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.example.com/frame.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "uploads/u42/20261112/0123…cdef.mp4" },
"role": "reference_video"
}
],
"resolution": "720p",
"duration": 5
}Quantas referências um modelo aceita, e se aceita vídeos, está na página do modelo. Cada vídeo de referência soma sua duração ao valor cobrado.
Envie um arquivo de referência
Quando o arquivo está na sua máquina e não tem um link público, envie-o primeiro e use a chave retornada.
- Peça um endereço de envio. Informe o tipo do arquivo e o tamanho exato em bytes:
POST https://api.vergora.ai/v1/uploads{ "content_type": "video/mp4", "size": 2376873 }- A resposta traz
key,upload_url,method(PUT) e osheadersa enviar. Envie o arquivo paraupload_urlcom exatamente esses cabeçalhos. O endereço vale por 15 minutos e só aceita o tipo e o tamanho declarados.
{
"object": "upload",
"key": "uploads/u42/20261112/0123456789abcdef0123456789abcdef.mp4",
"upload_url": "https://…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expires_at": 1794500000
}- Use a
keyem qualquer campo que aceite uma imagem ou um vídeo de referência.
| Tipo | Formatos aceitos | Limite de tamanho |
|---|---|---|
| Imagem | JPEG, PNG, WebP, GIF | 20 MB |
| Vídeo | MP4, MOV, WebM | 200 MB |
Uma chave só funciona para a conta que a criou. O arquivo enviado precisa ser de fato uma imagem ou um vídeo do tipo declarado; caso contrário, a solicitação que o usar será rejeitada. Os arquivos enviados são mantidos por tempo limitado; envie de novo quando uma chave deixar de funcionar.
Consulte o status da tarefa
Tarefas de vídeo costumam levar de algumas dezenas de segundos a vários minutos. Consulte o status a cada poucos segundos:
GET https://api.vergora.ai/v1/videos/{id}| Status | Significado |
|---|---|
queued | Na fila |
running ou in_progress | Em geração |
succeeded ou completed | Concluída; o vídeo pode ser baixado |
failed ou cancelled | Encerrada sem vídeo; o valor reservado é reembolsado |
A resposta mantém a estrutura da interface do modelo. Modelos cobrados por token também retornam um objeto usage com os tokens usados na cobrança.
Uma tarefa criada não significa que o vídeo já foi gerado. Guarde o id da tarefa para investigar falhas e conferir custos.
Baixe o vídeo
GET https://api.vergora.ai/v1/videos/{id}/contentO corpo da resposta é o arquivo de vídeo, normalmente MP4. Até a tarefa terminar com sucesso, este endpoint retorna 409 com o código video_not_ready: continue consultando o status em vez de repetir o download em loop. Os arquivos gerados ficam disponíveis por tempo limitado; salve-os no seu próprio armazenamento logo depois que a tarefa terminar.
Custo e novas tentativas
Modelos de vídeo têm preço por resolução, por segundo de vídeo ou por milhão de tokens; a página do modelo mostra todas as tarifas.
- Ao criar uma tarefa, um valor estimado é reservado do seu saldo com base na resolução, na proporção e na duração solicitadas, além do vídeo de entrada, se houver. Quando a solicitação não as informa, a estimativa usa 1080p, 16:9 e 15 segundos.
- Quando a tarefa termina com sucesso, a cobrança é liquidada pelo uso real (os tokens informados pelo modelo ou os segundos inteiros de vídeo gerado), sem nunca ultrapassar a reserva: se o uso for menor, a diferença é reembolsada; se for maior, o excedente não é cobrado.
- Se a tarefa falhar ou for cancelada, a reserva é reembolsada integralmente. Consultar o status e baixar o vídeo não tem custo.
| Resposta | Significado |
|---|---|
403 insufficient_user_quota | Seu saldo não cobre o valor estimado; nenhuma tarefa é criada |
503 model_price_not_configured | O modelo ainda não tem preço de vídeo |
409 video_not_ready | O download foi solicitado antes de a tarefa terminar |
Cada POST /v1/videos cria uma nova tarefa, cobrada separadamente. Depois de um tempo limite, verifique nos seus logs de API se a tarefa já foi criada antes de enviar a solicitação novamente.