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.

CampoTipo
modelstringObrigatório. O id de um modelo de vídeo.
promptstringObrigatório (exceto com draft_id). De 3 a 20.000 caracteres.
secondsinteger | "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".
resolutionstring480p, 720p (padrão), 1080p ou 4k; apenas as resoluções que o modelo oferece (veja a referência de modelos).
ratiostring16: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.
imagestringPrimeiro quadro: um link para uma imagem ou uma data URL (first_frame é aceito como o mesmo campo).
last_framestringÚltimo quadro, usado junto com image.
audiobooleanGerar som com o vídeo. Padrão true.
seedinteger-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_fixedbooleantrue mantém a câmera parada.
bitrate_modestringstandard (padrão) ou high. high pode falhar quando o modelo está ocupado; nesse caso há reembolso.
return_last_framebooleantrue: o último quadro fica guardado como imagem em GET /videos/{id}/last_frame.
reference_imagesstring[]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_videosstring[]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_audiosstring[]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_typestringCom reference_videos: auto, reference, edit ou extend (Seedance 2.5). edit e extend seguem o vídeo de entrada; omita seconds e ratio.
draftbooleanSeedance 2.5: true gera uma prévia em 480p pelo preço de 480p. resolution deve ser 480p.
draft_idstringTransforma 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çãoDe 4 a 30 segundos, ou "auto" para o modelo escolher
Resolução480p, 720p, 1080p
Proporção21:9, 16:9, 4:3, 1:1, 3:4, 9:16 ou adaptive (segue a entrada)
ModosTexto para vídeo; primeiro quadro ou primeiro e último quadro; referências; editar um vídeo; estender um vídeo
ReferênciasAté 30 imagens, 10 vídeos e 10 áudios. Áudio sozinho é aceito
SomFala, música e efeitos são gerados junto com a imagem (audio: true)
RascunhosSim: 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.
Prompt de exemplo
[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çãoDe 4 a 15 segundos, ou "auto"
ResoluçãoSeedance 2.0: 480p, 720p, 1080p, 4K. Fast e mini: 480p, 720p
Proporção21:9, 16:9, 4:3, 1:1, 3:4, 9:16
ModosTexto para vídeo; primeiro quadro ou primeiro e último quadro; referências; editar ou estender um vídeo pelo prompt
ReferênciasAté 9 imagens, 3 vídeos e 3 áudios. O áudio precisa vir com uma imagem ou um vídeo
SomFala, música e efeitos são gerados junto com a imagem (audio: true)
RascunhosNão
Arquivos 4KH.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
RostosImagens 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.
Prompt de exemplo
[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.