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 estafeta de bicicleta a correr contra uma torre do relógio ao amanhecer, uma ilustração editorial para o guia da Seedance 2.5 Flash API

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

ItemValor
Endpoint de submissãoPOST https://api.poyo.ai/api/generate/submit
Endpoint de estadoGET https://api.poyo.ai/api/generate/status/{task_id}
Cabeçalho 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, predefinição 720p
Proporçãoauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, predefinição auto
Áudiogenerate_audio, predefinição true
EntregaTarefa 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-Signature como base64(HMAC-SHA256(task_id + "." + timestamp, key)), com timestamp vindo de X-Webhook-Timestamp e a chave obtida em GET /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.

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 frame)image_urls não está vazioauto ou omitido; a saída segue o primeiro frame
Texto para vídeoSem multimédiaQualquer 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.

CampoRegra
promptObrigatório, string não vazia
durationInteiro obrigatório, 4–30
resolutionApenas 480p ou 720p; 1080p requer seedance-2.5
aspect_ratioUm dos sete valores; usa auto ou omite-o com image_urls
image_urls1–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_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 combinada de no máximo 30 s
reference_audio_urlsAté 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édiaHTTP 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ódigoTipoO que fazer
400validation_error, file_format_error, content_moderation_errorCorrige o pedido ou a multimédia; não repitas sem alterações
401authentication_errorVerifica o cabeçalho Bearer e se a chave ainda existe
402insufficient_credits_errorCarrega créditos e volta a submeter
429Limite de taxaRecua (1 s, 2 s, 4 s...) antes de voltares a consultar ou a submeter
500, 502, 503Servidor ou upstreamRepete a chamada de estado com backoff; verifica o estado antes de voltares a submeter
Tarefa failederror_message preenchidoRegista 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 acimaSegundos faturadosCréditosUSD
Teste cURL, 5 s 480p592.5$0.4625
Texto para vídeo, 30 s 720p301,230$6.15
Primeiro/último frame, 5 s 720p5205$1.025
Imagens de referência + áudio, 6 s 480p6111$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.

Share: