
A Seedance 2.5 Flash API é o nível mais rápido e mais barato da Seedance 2.5 API e, no PoYo, corresponde a um único ID de modelo: seedance-2.5-flash. A ByteDance lançou-o a 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-te de um primeiro pedido cURL até um ciclo de produção em Python, usando o esquema da documentação da Seedance 2.5 Flash API, verificado a 16 de novembro de 2026.
Seedance 2.5 Flash API num relance
| Item | Valor |
|---|---|
| Endpoint de submissão | POST https://api.poyo.ai/api/generate/submit |
| Endpoint de estado | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Cabeçalho 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, predefinição 720p |
| Proporção | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, predefinição auto |
| Áudio | generate_audio, predefinição true |
| Entrega | Tarefa assíncrona: consulta o estado ou define callback_url |
O teu primeiro pedido à Seedance 2.5 API com cURL
Exporta a tua chave como POYO_API_KEY e mantém-na no servidor, nunca em código de browser. Este é um pedido de texto para vídeo de 5 segundos em 480p, um primeiro teste barato de 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"
}
}'
Uma submissão bem-sucedida devolve code: 200 e um objeto data com task_id, status (sempre not_started logo após a submissão) e created_time. É um recibo, não um vídeo. Guarda o task_id e depois consulta-o:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Os estados passam por not_started, running, finished e failed. Quando a tarefa está finished, o URL do vídeo está em data.files[].file_url com file_type: "video"; em failed, lê data.error_message. Os ficheiros gerados ficam acessíveis durante 3 dias, por isso copia-os para o teu próprio armazenamento.
Python: submeter e consultar com um prazo rígido
A documentação de estado recomenda consultar a cada 2–5 segundos, recuar perante 429 e 5xx e definir sempre um tempo limite. O ciclo abaixo faz as três coisas e nunca volta a submeter quando o tempo se esgota, porque uma segunda submissão é uma segunda tarefa faturá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 do PoYo a 16 de novembro de 2026, um clip de 4 segundos em 480p terminou em cerca de dois minutos e um clip de 30 segundos em 720p em menos de três minutos, de ponta a ponta. Os tempos variam com a carga, por isso o prazo de 15 minutos é um limite de segurança e não uma estimativa.
Dispensa a consulta: usa callback_url
Acrescenta um callback_url de nível superior ao lado de model. Quando a tarefa passa a finished ou failed, o PoYo envia um POST cujo corpo é o objeto de dados da tarefa (task_id, status, files, created_time, error_message) sem o invólucro code/data. Segundo a documentação de webhooks de vídeo:
- O URL tem de ser HTTPS público, com no máximo 2048 carateres e sem IPs privados.
- Responde com um 2xx em 30 segundos; as entregas falhadas são repetidas até 5 vezes com backoff exponencial.
- Verifica
X-Webhook-Signaturecomobase64(HMAC-SHA256(task_id + "." + timestamp, key)), comtimestampvindo deX-Webhook-Timestampe a chave obtida emGET /api/api-keys/webhook-secret. - Torna o handler idempotente. Se todas as repetições falharem, o endpoint de estado continua a ter o resultado.
Os três modos de entrada, com corpos JSON
A API escolhe o modo a partir da multimédia que envias. Não existe nenhum 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 frame) | image_urls não está vazio | auto ou omitido; a saída segue o primeiro frame |
| Texto para vídeo | Sem multimédia | Qualquer valor suportado |
image_urls e os campos de referência vão em pedidos separados. Estes corpos são os exemplos documentados.
Texto para vídeo (30 segundos em 720p, com uma lista de planos temporizada 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 frame (um URL fixa a abertura; um segundo 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 (refere-te aos ficheiros pela ordem de carregamento 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 a aplicar antes de submeter
Verificá-las do lado do cliente poupa uma ida e volta ao servidor e dá aos teus utilizadores 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 requer seedance-2.5 |
aspect_ratio | Um dos sete valores; usa auto ou omite-o com image_urls |
image_urls | 1–2 URLs (primeiro frame, depois último); JPEG, PNG ou WebP, até 30 MB cada; não se combina com os 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 combinada de no máximo 30 s |
reference_audio_urls | Até 5; MP3 ou WAV, 2–30 s e até 15 MB cada; duração combinada de no máximo 30 s; requer uma imagem ou um vídeo de referência |
| Todos os URLs de multimédia | HTTP ou HTTPS públicos, descarregáveis diretamente (sem páginas de login nem pré-visualizações que expiram) |
As durações combinadas das referências são verificadas quando a tarefa é submetida. O esquema define também additionalProperties: false em input, por isso não envies campos de APIs de outros fornecedores, como seed ou negative_prompt.
Erros que vale a pena tratar
Lê sempre o campo code no corpo: alguns erros de validação do endpoint de submissão chegam 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 | Corrige o pedido ou a multimédia; não repitas sem alterações |
401 | authentication_error | Verifica o cabeçalho Bearer e se a chave ainda existe |
402 | insufficient_credits_error | Carrega créditos e volta a submeter |
429 | Limite de taxa | Recua (1 s, 2 s, 4 s...) antes de voltares a consultar ou a submeter |
500, 502, 503 | Servidor ou upstream | Repete a chamada de estado com backoff; verifica o estado antes de voltares a submeter |
Tarefa failed | error_message preenchido | Regista o ID da tarefa; as tarefas falhadas indicam credits_amount: 0 |
Como é calculada a primeira fatura
Sem vídeos de referência, o custo é o número de segundos de saída vezes a tarifa por segundo: 18,5 créditos ($0.0925) em 480p, 41 créditos ($0.205) em 720p, com 1 crédito = $0.005. O áudio gerado não acrescenta nada.
| Pedido acima | Segundos faturados | Créditos | USD |
|---|---|---|---|
| Teste cURL, 5 s 480p | 5 | 92.5 | $0.4625 |
| Texto para vídeo, 30 s 720p | 30 | 1,230 | $6.15 |
| Primeiro/último frame, 5 s 720p | 5 | 205 | $1.025 |
| Imagens de referência + áudio, 6 s 480p | 6 | 111 | $0.555 |
Acrescentar qualquer reference_video_urls muda para a tarifa mais baixa com vídeo (11,5 créditos em 480p, 25,5 em 720p), aplicada aos segundos faturados: a duração da saída mais a duração de cada vídeo de referência arredondada por defeito a segundos inteiros. A análise de preços da Seedance 2.5 API percorre esses casos. O valor cobrado por uma tarefa concluída aparece como credits_amount na resposta de estado.
Muda para o Seedance 2.5 para 1080p
Os campos do pedido são os mesmos, por isso passar um trabalho do Flash para o modelo Seedance 2.5 standard é uma mudança do ID do 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 indica resolution como obrigatório, por isso envia-o sempre, e o modelo standard permite até 30 imagens, 10 vídeos e 10 referências de áudio. Em 1080p custa 114 créditos ($0.57) por segundo. Para a decisão de encaminhamento, vê Seedance 2.5 Flash vs Seedance 2.5; para saberes como o Seedance 2.5 se compara com outro fornecedor, vê 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 hífenes é apenas o slug da página do modelo.
A Seedance 2.5 Flash API suporta 1080p? Não. Aceita 480p e 720p. Envia o mesmo corpo com "model": "seedance-2.5" e "resolution": "1080p" para obteres 1080p nativo.
Como desligo o áudio na Seedance 2.5 API? Define "generate_audio": false para um clip sem som, ou mantém o áudio ligado e retira camadas individuais no prompt, como "no background music".
Posso usar primeiros frames e imagens de referência num único pedido à Seedance 2.5 Flash API? Não. image_urls e os campos reference_* têm de ser enviados em pedidos separados.
Quanto tempo demora uma tarefa da Seedance 2.5 Flash API? No teste do 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. Consulta o estado ou usa um callback em vez de manteres um pedido aberto.
Sou cobrado se uma tarefa do Seedance 2.5 Flash falhar? Não. As tarefas falhadas não são cobradas, e o respetivo estado mostra credits_amount: 0.