
A Seedance 2.5 Flash API é o nível mais rápido e de menor custo da Seedance 2.5 API e, na PoYo, é um único ID de modelo: seedance-2.5-flash. A ByteDance o lançou em 12 de novembro de 2026; a página do modelo Seedance 2.5 Flash tem o playground e os preços atualizados. Este guia leva você de uma primeira requisição em cURL a um loop de produção em Python, usando o schema da documentação da Seedance 2.5 Flash API conferido em 16 de novembro de 2026.
Seedance 2.5 Flash API em resumo
| Item | Valor |
|---|---|
| Endpoint de envio | POST https://api.poyo.ai/api/generate/submit |
| Endpoint de status | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Header de autenticação | Authorization: Bearer $POYO_API_KEY |
| ID do modelo | seedance-2.5-flash (o slug da página, seedance-2-5-flash, não é um ID de modelo) |
| Campos obrigatórios | prompt, duration |
| Duração | Segundos inteiros, 4–30 |
| Resolução | 480p ou 720p, padrão 720p |
| Proporção | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, padrão auto |
| Áudio | generate_audio, padrão true |
| Entrega | Tarefa assíncrona: faça polling do status ou defina callback_url |
Sua primeira requisição à Seedance 2.5 API com cURL
Exporte sua chave como POYO_API_KEY e mantenha-a no servidor, nunca em código de navegador. Esta é uma requisição de texto para vídeo de 5 segundos em 480p, um primeiro teste de baixo custo por 92,5 créditos:
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
Um envio bem-sucedido retorna code: 200 e um objeto data com task_id, status (sempre not_started logo após o envio) e created_time. É um recibo, não um vídeo. Guarde o task_id e depois consulte-o:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Os status passam por not_started, running, finished e failed. Quando a tarefa está finished, a URL do vídeo está em data.files[].file_url com file_type: "video"; em failed, leia data.error_message. Os arquivos gerados ficam acessíveis por 3 dias, então copie-os para o seu próprio armazenamento.
Python: envio e polling com prazo rígido
A documentação de status recomenda fazer polling a cada 2–5 segundos, aplicar backoff em 429 e 5xx e sempre definir um timeout. O loop abaixo faz as três coisas e nunca reenvia em caso de timeout, porque um segundo envio é uma segunda tarefa cobrável.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
Como referência, nos testes da PoYo em 16 de novembro de 2026, um clipe de 4 segundos em 480p terminou em cerca de dois minutos e um clipe de 30 segundos em 720p em menos de três minutos, de ponta a ponta. Os tempos variam com a carga, então o prazo de 15 minutos é um limite de segurança, não uma estimativa.
Dispense o polling: use callback_url
Adicione um callback_url no nível superior, ao lado de model. Quando a tarefa ficar finished ou failed, a PoYo envia um POST cujo corpo é o objeto de dados da tarefa (task_id, status, files, created_time, error_message) sem o envelope code/data. Segundo a documentação de webhooks de vídeo:
- A URL precisa ser HTTPS pública, com no máximo 2048 caracteres e sem IPs privados.
- Responda com um 2xx em até 30 segundos; entregas com falha são repetidas até 5 vezes com backoff exponencial.
- Verifique
X-Webhook-Signaturecomobase64(HMAC-SHA256(task_id + "." + timestamp, key)), comtimestampvindo deX-Webhook-Timestampe a chave vinda deGET /api/api-keys/webhook-secret. - Torne o handler idempotente. Se todas as tentativas falharem, o endpoint de status ainda tem o resultado.
Os três modos de entrada, com corpos JSON
A API escolhe o modo pela mídia que você envia. Não existe um campo mode.
| Modo | Selecionado quando | Proporção |
|---|---|---|
| Referência para vídeo | Qualquer um de reference_image_urls, reference_video_urls, reference_audio_urls não está vazio | Qualquer valor suportado |
| Imagem para vídeo (primeiro/último quadro) | image_urls não está vazio | auto ou omitido; a saída segue o primeiro quadro |
| Texto para vídeo | Sem mídia | Qualquer valor suportado |
image_urls e os campos de referência vão em requisições separadas. Estes corpos são os exemplos documentados.
Texto para vídeo (30 segundos em 720p, com uma lista de planos cronometrada no prompt):
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
Primeiro e último quadro (uma URL fixa a abertura; uma segunda fixa o final):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
Referência para vídeo (refira-se aos arquivos pela ordem de envio como @Image1, @Video1, @Audio1):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
Regras de validação para aplicar antes de enviar
Verificar isto no cliente economiza uma ida e volta e dá aos seus usuários uma mensagem mais clara do que um 400 genérico.
| Campo | Regra |
|---|---|
prompt | Obrigatório, string não vazia |
duration | Inteiro obrigatório, 4–30 |
resolution | Apenas 480p ou 720p; 1080p exige seedance-2.5 |
aspect_ratio | Um dos sete valores; use auto ou omita com image_urls |
image_urls | 1–2 URLs (primeiro e depois último quadro); JPEG, PNG ou WebP, até 30 MB cada; não pode ser combinado com campos de referência |
reference_image_urls | Até 10; JPEG, PNG ou WebP, até 30 MB cada |
reference_video_urls | Até 5; MP4 ou MOV, 2–30 s e até 200 MB cada; duração somada de no máximo 30 s |
reference_audio_urls | Até 5; MP3 ou WAV, 2–30 s e até 15 MB cada; duração somada de no máximo 30 s; exige uma imagem ou vídeo de referência |
| Todas as URLs de mídia | HTTP ou HTTPS públicas, com download direto (sem páginas de login nem prévias que expiram) |
As durações somadas das referências são verificadas quando a tarefa é enviada. O schema também define additionalProperties: false em input, então não envie campos das APIs de outros fornecedores, como seed ou negative_prompt.
Erros que vale a pena tratar
Sempre leia o campo code no corpo: alguns erros de validação do endpoint de envio voltam com HTTP 200 e "code": 400. A referência de códigos de erro lista estes:
| Código | Tipo | O que fazer |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Corrija a requisição ou a mídia; não repita sem alterações |
401 | authentication_error | Verifique o header Bearer e se a chave ainda existe |
402 | insufficient_credits_error | Recarregue e depois reenvie |
429 | Rate limit | Aplique backoff (1 s, 2 s, 4 s...) antes de fazer polling ou enviar de novo |
500, 502, 503 | Servidor ou upstream | Repita a chamada de status com backoff; verifique o status antes de reenviar |
Tarefa failed | error_message preenchido | Registre o ID da tarefa; tarefas com falha informam credits_amount: 0 |
Como a primeira cobrança é calculada
Sem vídeos de referência, o custo é a quantidade de segundos de saída vezes a tarifa por segundo: 18,5 créditos (US$ 0,0925) em 480p e 41 créditos (US$ 0,205) em 720p, com 1 crédito = US$ 0,005. O áudio gerado não acrescenta nada.
| Requisição acima | Segundos cobrados | Créditos | USD |
|---|---|---|---|
| Teste em cURL, 5 s 480p | 5 | 92.5 | $0.4625 |
| Texto para vídeo, 30 s 720p | 30 | 1,230 | $6.15 |
| Primeiro/último quadro, 5 s 720p | 5 | 205 | $1.025 |
| Imagens de referência + áudio, 6 s 480p | 6 | 111 | $0.555 |
Adicionar qualquer reference_video_urls muda para a tarifa menor com vídeo (11,5 créditos em 480p, 25,5 em 720p), aplicada aos segundos cobrados: a duração da saída mais a duração de cada vídeo de referência arredondada para baixo em segundos inteiros. O detalhamento de preços da Seedance 2.5 API calcula esses casos. A cobrança de uma tarefa concluída aparece como credits_amount na resposta de status.
Mude para o Seedance 2.5 para ter 1080p
Os campos da requisição são os mesmos, então mover um job do Flash para o modelo Seedance 2.5 padrão é uma troca de ID de modelo:
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
Dois detalhes: a documentação do seedance-2.5 lista resolution como obrigatório, então sempre o envie, e o modelo padrão permite até 30 imagens, 10 vídeos e 10 áudios de referência. Em 1080p, ele custa 114 créditos (US$ 0,57) por segundo. Para a decisão de roteamento, veja Seedance 2.5 Flash vs Seedance 2.5; para ver como o Seedance 2.5 se compara com outro fornecedor, veja Kling 4.0 vs Seedance 2.5.
Perguntas frequentes
Qual é o ID do modelo da Seedance 2.5 Flash API? seedance-2.5-flash, com pontos. O seedance-2-5-flash com hifens é apenas o slug da página do modelo.
A Seedance 2.5 Flash API suporta 1080p? Não. Ela aceita 480p e 720p. Envie o mesmo corpo com "model": "seedance-2.5" e "resolution": "1080p" para ter 1080p nativo.
Como desativo o áudio na Seedance 2.5 API? Defina "generate_audio": false para um clipe sem som, ou mantenha o áudio ativado e remova camadas individuais no prompt, como "no background music".
Posso usar primeiros quadros e imagens de referência em uma mesma requisição da Seedance 2.5 Flash? Não. image_urls e os campos reference_* precisam ser enviados em requisições separadas.
Quanto tempo leva uma tarefa da Seedance 2.5 Flash API? No teste da PoYo de 16 de novembro de 2026, cerca de dois minutos para 4 segundos em 480p e menos de três minutos para 30 segundos em 720p, de ponta a ponta. Faça polling ou use um callback em vez de manter uma requisição aberta.
Sou cobrado se uma tarefa da Seedance 2.5 Flash falhar? Não. Tarefas com falha não são cobradas, e o status delas mostra credits_amount: 0.