how-tos

Seedance 2.5 API: guia para chamar o Seedance 2.5 Flash com cURL e Python

Poyo.ai Team
11 min read
Share:

Um entregador de bicicleta apostando corrida com uma torre de relógio ao amanhecer, ilustração editorial do guia da Seedance 2.5 Flash API

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

ItemValor
Endpoint de envioPOST https://api.poyo.ai/api/generate/submit
Endpoint de statusGET https://api.poyo.ai/api/generate/status/{task_id}
Header de autenticaçãoAuthorization: Bearer $POYO_API_KEY
ID do modeloseedance-2.5-flash (o slug da página, seedance-2-5-flash, não é um ID de modelo)
Campos obrigatóriosprompt, duration
DuraçãoSegundos inteiros, 4–30
Resolução480p ou 720p, padrão 720p
Proporçãoauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, padrão auto
Áudiogenerate_audio, padrão true
EntregaTarefa 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-Signature como base64(HMAC-SHA256(task_id + "." + timestamp, key)), com timestamp vindo de X-Webhook-Timestamp e a chave vinda de GET /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.

ModoSelecionado quandoProporção
Referência para vídeoQualquer um de reference_image_urls, reference_video_urls, reference_audio_urls não está vazioQualquer valor suportado
Imagem para vídeo (primeiro/último quadro)image_urls não está vazioauto ou omitido; a saída segue o primeiro quadro
Texto para vídeoSem mídiaQualquer 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.

CampoRegra
promptObrigatório, string não vazia
durationInteiro obrigatório, 4–30
resolutionApenas 480p ou 720p; 1080p exige seedance-2.5
aspect_ratioUm dos sete valores; use auto ou omita com image_urls
image_urls1–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_urlsAté 10; JPEG, PNG ou WebP, até 30 MB cada
reference_video_urlsAté 5; MP4 ou MOV, 2–30 s e até 200 MB cada; duração somada de no máximo 30 s
reference_audio_urlsAté 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ídiaHTTP 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ódigoTipoO que fazer
400validation_error, file_format_error, content_moderation_errorCorrija a requisição ou a mídia; não repita sem alterações
401authentication_errorVerifique o header Bearer e se a chave ainda existe
402insufficient_credits_errorRecarregue e depois reenvie
429Rate limitAplique backoff (1 s, 2 s, 4 s...) antes de fazer polling ou enviar de novo
500, 502, 503Servidor ou upstreamRepita a chamada de status com backoff; verifique o status antes de reenviar
Tarefa failederror_message preenchidoRegistre 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 acimaSegundos cobradosCréditosUSD
Teste em cURL, 5 s 480p592.5$0.4625
Texto para vídeo, 30 s 720p301,230$6.15
Primeiro/último quadro, 5 s 720p5205$1.025
Imagens de referência + áudio, 6 s 480p6111$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.

Share: