API de geração de vídeo
Como gerar vídeo por /videos: inicie uma tarefa, acompanhe e baixe o arquivo. Campos, arquivos de referência, rascunhos e cobrança.
Video
Os modelos de vídeo rodam como tarefas. POST /videos inicia uma e retorna o id na hora; consulte GET /videos/{id} a cada poucos segundos até status ser completed ou failed (normalmente de 1 a 5 minutos) e então baixe: a tarefa concluída traz uma url (um link para o arquivo, válido por uma semana e renovado a cada leitura; se não conseguimos armazenar o arquivo, url é o caminho /v1/videos/{id}/content) e GET /videos/{id}/content sempre busca o arquivo. O id de qualquer resposta (chatcmpl-…, img_…, video_…) e o request_id de qualquer erro são o que você deve informar ao suporte.
| Campo | Tipo | |
|---|---|---|
model | string | Obrigatório. O id de um modelo de vídeo. |
prompt | string | Obrigatório (exceto com draft_id). De 3 a 20.000 caracteres. |
seconds | integer | "auto" | Duração (duration é aceito como o mesmo campo). Seedance 2.5: de 4 a 30; Seedance 2.0: de 4 a 15. "auto" deixa o modelo escolher; a duração máxima é reservada e você paga pelo que ele gerar. Padrão 5; com reference_videos o padrão é "auto". |
resolution | string | 480p, 720p (padrão), 1080p ou 4k; apenas as resoluções que o modelo oferece (veja a referência de modelos). |
ratio | string | 16:9 (padrão), 9:16, 1:1, 4:3, 3:4, 21:9 ou adaptive. Com reference_videos o padrão segue o vídeo de entrada. |
image | string | Primeiro quadro: um link para uma imagem ou uma data URL (first_frame é aceito como o mesmo campo). |
last_frame | string | Último quadro, usado junto com image. |
audio | boolean | Gerar som com o vídeo. Padrão true. |
seed | integer | -1 para uma seed aleatória (padrão), ou um número inteiro de 1 a 4294967295 para repetir um resultado no mesmo modelo. A resposta mostra a seed que você enviou, ou -1 quando foi aleatória. |
camera_fixed | boolean | true mantém a câmera parada. |
bitrate_mode | string | standard (padrão) ou high. high pode falhar quando o modelo está ocupado; nesse caso há reembolso. |
return_last_frame | boolean | true: o último quadro fica guardado como imagem em GET /videos/{id}/last_frame. |
reference_images | string[] | Links de imagens ou data URLs: até 30 no Seedance 2.5, 9 no Seedance 2.0 (jpeg, png, webp, bmp, tiff, gif; até 30 MB; cada lado de 300 a 6000 px). |
reference_videos | string[] | Links públicos de MP4/MOV: até 10 no Seedance 2.5, 3 no Seedance 2.0; de 2 a 15 s cada, 480p ou 720p, até 50 MB. A duração deles também é cobrada. |
reference_audios | string[] | Links públicos de WAV/MP3: até 10 no Seedance 2.5, 3 no Seedance 2.0; de 2 a 15 s cada, até 15 MB. |
task_type | string | Com reference_videos: auto, reference, edit ou extend (Seedance 2.5). edit e extend seguem o vídeo de entrada; omita seconds e ratio. |
draft | boolean | Seedance 2.5: true gera uma prévia em 480p pelo preço de 480p. resolution deve ser 480p. |
draft_id | string | Transforma um rascunho concluído no vídeo final em 1080p. Envie apenas model e draft_id: o prompt, as referências, a duração, a proporção, o áudio e a seed vêm do rascunho. Os rascunhos duram 7 dias. |
As referências são numeradas por tipo na ordem em que você as envia: o primeiro item de reference_images é a imagem 1, o segundo a imagem 2, e o mesmo vale para vídeos e áudios. Chame-as assim no prompt, como o playground faz com [Image 1], [Video 1] e [Audio 1], por exemplo "The woman in [Image 1] walks through the street of [Video 1]". Enviar mais arquivos do que o modelo aceita é recusado, não cortado.
status é queued, in_progress, completed ou failed. Uma tarefa concluída tem usage.video_tokens e usage.cost_usd; uma que falhou não é cobrada e traz error.code e error.message: generation_failed (o modelo não conseguiu gerar o vídeo), invalid_reference (um dos arquivos de referência foi recusado; a mensagem diz qual) ou timeout.
// GET https://api.apistore.cloud/v1/videos/video_...
{
"id": "video_0123456789abcdef0123456789abcdef",
"object": "video",
"model": "MODEL_NAME",
"status": "completed",
"created_at": 1793984023,
"completed_at": 1793984214,
"prompt": "A red paper boat drifting across a calm lake at sunrise",
"resolution": "720p",
"ratio": "16:9",
"seconds": 5,
"draft": false,
"seed": 49873,
"url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
"last_frame": null,
"error": null,
"usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}Rascunhos (Seedance 2.5): gere primeiro uma prévia barata em 480p e depois transforme a que você gostar no vídeo final em 1080p com a mesma seed e as mesmas configurações.
# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'
# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "draft_id": "video_..."}'O custo estimado é retido do seu saldo quando a tarefa começa: (segundos do vídeo de entrada + segundos de saída) em tokens de vídeo pelo preço daquela resolução. Ao terminar, você paga pelos tokens realmente gerados (cerca de 108K para 5 segundos em 720p) e o restante é liberado; uma tarefa que falha não custa nada. Em Configurações você pode trocar a cobrança de vídeo da tabela de preços por token para "por USD": a cobrança do próprio fornecedor pelo trabalho a preço de tabela, menos seu desconto. Cada registro de faturamento informa qual foi aplicada.
Guias de modelos
No que cada família de modelos de vídeo é boa, seus limites e como escrever prompts que o modelo siga.
Seedance 2.5
O modelo de formato longo: até 30 segundos em uma tarefa, muitos arquivos de referência, e edição ou extensão de um vídeo existente. Ele escreve e fala 11 idiomas, entre eles inglês e vietnamita.
| Em resumo | |
|---|---|
| Duração | De 4 a 30 segundos, ou "auto" para o modelo escolher |
| Resolução | 480p, 720p, 1080p |
| Proporção | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 ou adaptive (segue a entrada) |
| Modos | Texto para vídeo; primeiro quadro ou primeiro e último quadro; referências; editar um vídeo; estender um vídeo |
| Referências | Até 30 imagens, 10 vídeos e 10 áudios. Áudio sozinho é aceito |
| Som | Fala, música e efeitos são gerados junto com a imagem (audio: true) |
| Rascunhos | Sim: primeiro uma prévia em 480p, depois o vídeo final a partir da que você gostar |
Como escrever prompts
- Comece com uma frase. Diga quem, onde, o que acontece, o estilo e a câmera em uma única linha. Depois acrescente os detalhes abaixo.
- Vincule cada referência. Chame cada arquivo pelo número e diga para que serve: "[Image 1] is the lead actress, [Image 2] is the cafe, follow the camera of [Video 1]". Não conte com texto escrito dentro de uma imagem para dizer quem é alguém.
- Use uma linha do tempo em vídeos longos. Divida a história em intervalos de segundos inteiros sem lacunas ("0-5 s", "5-12 s") ou em tomadas numeradas, e dê a cada um sua imagem, câmera, ação, fala e som. Com muito pouco por intervalo o modelo improvisa; com demais, ele corta com muita frequência.
- Poucos sujeitos. De um a cinco sujeitos se mantêm melhor. Várias vistas do mesmo sujeito servem como referência até cinco sujeitos; além disso, envie uma vista de cada.
- Edição (task_type: edit). Diga o que muda e onde, de quê para quê, com os segundos quando só uma parte muda: "In [Video 1], from second 4 to 6 she waves instead of nodding; everything else stays". O resultado mantém a duração e a proporção da entrada, então omita seconds e ratio. Vídeos com menos de 20 segundos são editados melhor.
- Extensão (task_type: extend). Diga a direção e o que acontece em seguida: "Extend [Video 1] forward: she opens the door and walks into the rain". A proporção segue o vídeo de entrada.
- Primeiro e último quadro. Envie-os como image e last_frame, com as mesmas proporções, para o vídeo começar e terminar exatamente ali. Uma imagem de referência chamada de "the first frame" no prompt é seguida com menos rigor.
- Storyboards e quadros-chave. Uma folha de storyboard (15 quadros ou menos, traço simples, sem texto) orienta a trama, mas não é seguida quadro a quadro. Para quadros estritos, envie imagens separadas e comece com "Use Images 1 to 5 in order as keyframes".
- Câmera. Os termos comuns de cinema funcionam como estão: push in, pan, tracking shot, orbit, handheld, low angle, long take. Explique termos raros em poucas palavras, e diga quando uma transição acontece, além de como.
- O que deixar de fora. Escreva o que você quer em vez do que não quer. As duas exceções que funcionam bem: "No subtitles" e "No background music, only ambient sound".
- Fala. Escreva as falas assim: nome, estado de espírito entre colchetes e depois as palavras. Um idioma por fala. Para palavras que precisam aparecer escritas com exatidão na tela, envie-as como imagem.
[Image 1] is the fisherman, [Image 2] is his boat. Documentary style, natural light. 0-6 s: wide shot at water level, the boat drifts through morning mist. Slow push in. 6-14 s: medium shot, he pulls the net in, hand over hand. Water drips from the rope. 14-20 s: close-up on his face as he looks at the catch and smiles. Ambient sound only: water, wood, gulls. No subtitles, no background music.
Seedance 2.0
Três modelos que aceitam a mesma requisição e diferem em qualidade, velocidade e preço: Seedance 2.0 para a melhor imagem, Seedance 2.0 fast para um equilíbrio entre velocidade e custo, Seedance 2.0 mini para o menor preço.
| Em resumo | |
|---|---|
| Duração | De 4 a 15 segundos, ou "auto" |
| Resolução | Seedance 2.0: 480p, 720p, 1080p, 4K. Fast e mini: 480p, 720p |
| Proporção | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
| Modos | Texto para vídeo; primeiro quadro ou primeiro e último quadro; referências; editar ou estender um vídeo pelo prompt |
| Referências | Até 9 imagens, 3 vídeos e 3 áudios. O áudio precisa vir com uma imagem ou um vídeo |
| Som | Fala, música e efeitos são gerados junto com a imagem (audio: true) |
| Rascunhos | Não |
| Arquivos 4K | H.265 com cor de 10 bits. Alguns players não conseguem abrir; o VLC e as versões atuais do Chrome, Edge e Safari conseguem |
| Rostos | Imagens e vídeos de referência que mostram o rosto de uma pessoa real são recusados |
Como escrever prompts
- A fórmula. Sujeito, ação, lugar, luz e cor, câmera, estilo, qualidade e depois o que evitar. Defina primeiro quem faz o quê, depois onde e depois como é filmado.
- Defina cada sujeito uma vez. Dê duas ou três características fixas (roupa, cabelo, porte) e um rótulo, e use sempre o mesmo rótulo: "The girl in the red coat from [Image 1]".
- Escreva tomadas, não segundos. Numere as tomadas: "Shot 1: ... Shot 2: ...", cada uma com sua câmera, ação, lugar e som. Tempos exatos como "0-3 s" não são respeitados de forma confiável neste modelo.
- Um movimento de câmera por tomada. Push in, ou pan, ou track. Combinar vários movimentos em uma tomada deixa o resultado instável.
- Descreva o movimento fisicamente. Diga a parte do corpo, quanto e com que velocidade. Movimento lento e contínuo funciona melhor. Mostre uma emoção pelo corpo ("lowers her head, eyes reddening") em vez de nomeá-la.
- Use poucas referências. Quatro ou cinco bastam: uma ou duas para o personagem, uma para o lugar, um vídeo para a câmera, um áudio para o clima. Mais de quatro pessoas como referência reduz a estabilidade, e várias vistas de uma mesma pessoa não são recomendadas.
- Rostos que se mantêm. Envie um close da cabeça e uma imagem de corpo inteiro, e diga qual é para o rosto e qual para a roupa. Coloque os arquivos mais importantes primeiro.
- Edição. Cite o vídeo diretamente e diga o que muda: "Strictly edit [Video 1]: replace the cat with the lion from [Image 1], keep everything else". Não escreva "reference [Video 1]" aqui, ou ele será tratado apenas como referência.
- Extensão. "Extend [Video 1] forward" ou "backward", e depois o que acontece. Dois ou três clipes podem ser unidos com uma transição entre eles, 15 segundos no total. Acrescente "end with [Video 1]" para manter o material original no resultado.
- Fala e texto. Coloque as falas entre chaves e mantenha um único idioma: She says {We are late}. Para texto na tela, informe as palavras, quando, onde e como aparecem. Use caracteres comuns.
- O que evitar. Legendas e logos ainda podem aparecer. "Keep it subtitle-free" e "Do not generate a logo or watermark" reduzem isso; remover o texto dos seus arquivos de referência também ajuda.
[Image 1] is the girl in the red coat, [Image 2] is the night market. Follow the camera of [Video 1].
Shot 1: wide shot, she walks in between the stalls. Slow push in.
Shot 2: medium shot, she stops at a lantern stall and lifts one lantern. Fixed camera.
Shot 3: close-up, warm light on her face. She says {This one}.
Cinematic, warm tones, rich detail. Keep it subtitle-free. Do not generate a logo or watermark.