Tutorial da API Seedance 2.5 Flash: tarefas assíncronas, limites e erros

AIHubMix8 min de leitura
Tutorial da API Seedance 2.5 Flash: tarefas assíncronas, limites e erros

Use doubao-seedance-2-5-flash com POST /ai/v1/videos, consulte o status da tarefa e baixe o resultado. O esquema atual do AIHubMix oferece saída em 480p/720p, clipes de 4–30 segundos e até 10 referências de imagem, 5 de vídeo e 5 de áudio. Clientes antigos que usam /v1/videos precisam alterar o endpoint e o ID do modelo.

Este guia foi verificado em 16 de novembro de 2026. Tanto o ID curto acima quanto doubao-seedance-2-5-flash-261115 retornaram um esquema do modelo e rejeitaram uma solicitação em 1080p com 400 schema_violation. Uma tentativa separada de criação de 4 segundos em 480p retornou 402 insufficient_quota; nenhum vídeo foi gerado. O fluxo de trabalho abaixo segue o esquema e a documentação atuais, mas a geração bem-sucedida, a latência, a saída MOV e a edição não foram verificadas de ponta a ponta nesta checagem.

Pré-requisitos e descoberta do esquema

A página do modelo Seedance 2.5 Flash lista o modelo com o ID curto usado ao longo deste guia. Antes de enviar uma tarefa:

  1. Ative as tarefas de mídia assíncronas no console do AIHubMix. O erro documentado para contas sem esse recurso é 403 async_not_enabled.
  2. Certifique-se de que a chave de API tenha acesso e que a conta tenha crédito suficiente. A checagem ao vivo retornou 402 insufficient_quota com a mensagem Your account has insufficient quota. Add credits and try again.
  3. Exporte AIHUBMIX_API_KEY no shell. Não inclua a chave em arquivos-fonte nem em código executado no navegador.
  4. Obtenha o esquema atual; a solicitação de descoberta não requer autenticação.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

O esquema de 16 de novembro lista apenas /ai/v1/videos para Flash. Ele aceita os valores resolution 480p e 720p (padrão 720p), um número inteiro de duration entre 4 e 30, ou -1 para que o modelo selecione a duração. Use uma duração explícita se precisar de um orçamento previsível.

Criar, consultar e baixar

A API de geração de vídeo do AIHubMix separa a criação, as consultas de status e os downloads. Uma resposta HTTP de sucesso na criação significa que a tarefa foi aceita; apenas status: "completed" confirma a conclusão. Uma consulta pode retornar HTTP 200 mesmo quando a tarefa tem status: "failed".

Enviar uma tarefa de texto para vídeo

Este exemplo solicita um clipe de produto de 10 segundos, em 720p e 16:9, com áudio. Ele usa apenas texto, portanto não depende de imagens de referência hospedadas em outro lugar.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Armazene imediatamente o id da tarefa retornado. Consulte GET /ai/v1/videos/{id} a cada 15 segundos até que o status seja completed, failed ou cancelled. Use a rota de detalhes do vídeo para consultar tarefas ativas: ela atualiza o status do provedor, enquanto a lista unificada de tarefas não substitui essa checagem. Após a conclusão, baixe o vídeo usando GET /ai/v1/videos/{id}/content, com o mesmo cabeçalho Bearer.

Um cliente Python completo

Instale a dependência com python3 -m pip install requests, salve o código a seguir como seedance_flash.py e execute python3 seedance_flash.py no shell que contém sua chave de API. Este exemplo implementa o fluxo documentado; o erro de cota acima impediu um teste completo de geração.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

O prazo de 20 minutos é um limite de espera do lado do cliente, não um cancelamento no servidor nem uma garantia de tempo de geração. Se a consulta de status ou o download falhar, mantenha o ID da tarefa e tente novamente essa operação. Não envie automaticamente outra solicitação de geração após um tempo limite ou quando o estado do provedor for incerto.

Nas tarifas oficiais de inferência online da BytePlus, o Flash custa $7.00 por milhão de tokens sem entrada de vídeo ou $4.30 com entrada de vídeo em 480p/720p. Para o exemplo apenas com texto, a estimativa é 10 × 1280 × 720 × 24 / 1024 = 216,000 tokens: $1.51 no Flash, contra $2.31 no flagship 2.5 em 720p. Estas são estimativas calculadas com base nas tarifas da BytePlus, não uma cobrança medida do AIHubMix.

Referências e webhooks

Para orientar um clipe com mídia, adicione entradas input_references que contenham um type (image_url, video_url ou audio_url) e um url que aponte para uma mídia acessível. O esquema limita esses tipos a 10 / 5 / 5. Para controlar o primeiro e o último quadro, use frame_images; cada entrada tem um frame_type e um image_url.url aninhado. Não combine frame_images e input_references não vazios. Os fluxos de trabalho com quadros exigem aspect_ratio: "adaptive", e é necessário fornecer o primeiro quadro para usar um último quadro.

A documentação de Tarefas assíncronas descreve callbacks HTTPS por meio de webhook_url. O esquema atual do Flash inclui esse campo, mas omite webhook_events_filter e define additionalProperties: false; portanto, omita o filtro ao seguir o esquema deste modelo. A documentação informa que, por padrão, são enviados os eventos completed, failed e cancelled. A entrega é feita pelo menos uma vez, com até seis tentativas e intervalos de repetição de 1, 4, 16, 64 e 256 segundos; elimine duplicatas com base em event_id. Os callbacks no nível da tarefa não têm um segredo de assinatura separado, portanto consulte a tarefa para confirmar o estado final. A documentação descreve assinaturas no nível da conta para aplicações que precisam verificar a assinatura.

Erros: o que foi medido e o que a documentação descreve

1080p: rejeição do esquema observada

Os dois IDs de modelo do AIHubMix retornaram HTTP 400 para uma solicitação de 4 segundos com resolution: "1080p". Os campos de erro retornados foram:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

A resposta também continha um ID de rastreamento da solicitação, omitido aqui. Trata-se de uma rejeição observada no gateway, não de um erro inferido do provedor upstream. Isso não comprova uma geração bem-sucedida nem uma medição de velocidade.

As outras restrições abaixo vêm do esquema atual do Flash; essas combinações inválidas não foram enviadas separadamente na checagem ao vivo.

Problema de entrada Requisito do esquema Solução
Saída em 4K 480p ou 720p Reduza a resolução
Excesso de referências 10 imagens / 5 vídeos / 5 áudios Reduza o conjunto
Dois arrays de referência Um array não vazio Escolha um fluxo de trabalho
Apenas o último quadro O primeiro quadro também é obrigatório Forneça os dois quadros
Proporção fixa com quadros Proporção adaptável Use o modo adaptável

Referências de pessoas reais: use recursos verificados

O AIHubMix documenta doubao_real_person_required quando o Doubao retorna sua rejeição de privacidade específica para uma imagem de pessoa real. Esse erro não ocorreu nesta checagem. A mensagem documentada é:

Esta solicitação usa uma imagem de pessoa real. Conclua a verificação de pessoa real e use uma referência de recurso ativa. Consulte https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Siga o Guia de recursos de pessoas reais do Doubao: crie um grupo em /ai/v1/asset-groups, crie uma sessão de verificação em /ai/v1/asset-groups/{id}/verification-sessions, peça à pessoa retratada que conclua a verificação na web, registre o recurso em /ai/v1/asset-groups/{id}/assets e aguarde até que ele esteja ativo. Use asset://<ASSET_ID> na referência de geração. Uma URL de foto bruta não substitui o fluxo de consentimento e registro do recurso.

Cota, tamanho da solicitação e downloads

O erro medido 402 insufficient_quota impediu que a solicitação com resolução válida chegasse à etapa de geração. Adicione crédito antes de tentar novamente; alterar um prompt correto ou o ID do modelo não resolve essa resposta. 403 async_not_enabled é um erro diferente, documentado como pré-requisito, que exige ativação no console.

O AIHubMix documenta um limite de 32 MiB para o corpo da solicitação e o erro 413 request_too_large. URLs públicas evitam que a expansão do Base64 aumente o corpo da solicitação, embora a mídia referenciada ainda precise respeitar os limites de tamanho e formato do próprio modelo.

Salve prontamente o vídeo concluído. O guia de integração existente do AIHubMix para Seedance 2.5 alerta que as URLs de saída têm validade curta, de cerca de 30 minutos; o prazo fixo de retenção do Flash não foi verificado aqui. A API de vídeo pode retornar expires_at: null, o que não garante armazenamento por tempo indeterminado. Entre os erros de download documentados estão 410 artifact_expired e 429 too_many_downloads. Se um download encontrar um erro temporário de serviço, tente baixá-lo novamente usando a tarefa existente, em vez de gerar o clipe outra vez.

Armadilhas de migração que podem afetar até uma solicitação válida

O guia do Volcengine para Seedance 2.5 inclui explicitamente o Flash na família e confirma a saída MOV, a edição e a extensão, mas é preciso distinguir esses recursos do fornecedor daquilo que foi verificado por meio do gateway.

  • Os campos de MOV e edição estão disponíveis, mas não foram testados de ponta a ponta aqui. O esquema do Flash aceita extra.output_format: "mp4" ou "mov", além dos valores auto, reference, edit e extend para extra.omni_reference_task_type. Se você enviar explicitamente o campo de tipo de tarefa, o esquema exige input_references não vazio. edit também exige uma referência de vídeo, proporção adaptável e duration: -1; extend exige uma referência de vídeo e proporção adaptável.
  • Especificar o tipo de tarefa não garante que o modelo concorde. A Ark documenta InvalidParameter.TaskTypeConstraint assíncrono quando o tipo de tarefa inferido entra em conflito com os parâmetros, e InvalidParameter.TaskTypeMismatch quando o tipo inferido difere daquele solicitado explicitamente. O mapeamento exato no AIHubMix não foi medido; inspecione o error retornado pela tarefa em vez de presumir um código específico do gateway.
  • O Flash não oferece a promoção do modo Draft. O fornecedor limita o fluxo de trabalho em duas etapas, de Draft em 480p para a versão final, ao flagship 2.5. O Flash não oferece esse recurso, e os esquemas atuais do AIHubMix para ambos os modelos omitem draft e draft_task.
  • A entrada de vídeo altera a cobrança. A cobrança oficial considera a duração dos vídeos de entrada e de saída e pode impor um piso mínimo de tokens. A tarifa de $4.30/M não garante que uma tarefa guiada por vídeo custe menos do que uma tarefa equivalente apenas com texto. Confira o uso real e a cobrança da conta, em vez de confiar apenas na fórmula.
  • Algumas descrições continuam ambíguas. O esquema do gateway do Flash expõe extra.priority, extra.safety_identifier e extra.tools, mas as descrições ainda dizem “somente para a série 2.0”. A referência de criação de tarefas do Ark também lista priority e tools para a família 2.5. A exposição no esquema, por si só, não confirma o efeito desses campos no AIHubMix; valide o recurso específico antes de confiar nele em produção.

Checklist antes de começar

  • Ative as tarefas assíncronas e confira o crédito da conta.
  • Use o ID curto do Flash com /ai/v1/videos e consulte o esquema atual.
  • Escolha 480p ou 720p e uma duração explícita entre 4–30 segundos.
  • Limite as referências a 10 imagens, 5 vídeos e 5 clipes de áudio.
  • Mantenha as referências de quadros separadas e use a proporção adaptativa para elas.
  • Encaminhe referências de semelhança com pessoas reais por meio de ativos verificados e ativos.
  • Armazene o ID da tarefa, confira o status terminal da tarefa e baixe o resultado sem demora.
  • Se o estado da geração for incerto, repita as consultas ou os downloads para uma tarefa existente.

Perguntas frequentes

Posso usar o caminho compatível com OpenAI /v1/videos para o Flash?
O esquema atual do Flash lista apenas /ai/v1/videos. Use esse caminho assíncrono nativo para os exemplos deste guia.

Por que uma solicitação com imagem de quadro falha com aspect_ratio: "16:9"?
O esquema do Flash exige aspect_ratio: "adaptive" quando frame_images não estiver vazio. Um quadro final também exige um quadro inicial, e as referências de quadros não podem ser combinadas com input_references não vazio.

Como corrijo doubao_real_person_required?
Siga o fluxo de verificação pessoal e registro de ativos, aguarde até que o ativo fique ativo e faça referência a ele usando um URI de ativo. O código indica uma rejeição específica de privacidade do Doubao; ela não foi reproduzida nesta verificação.

Por que um vídeo de referência curto pode custar mais do que o previsto pela fórmula?
As regras de cobrança do fornecedor podem aplicar um mínimo de tokens quando a entrada inclui vídeo. A fórmula é uma estimativa; confira o consumo real e os registros de cobrança da conta para saber o valor cobrado.

Gerações com falha ou rejeições na moderação custam dinheiro?
As regras oficiais de cobrança da BytePlus e da Volcengine cobram pelas gerações bem-sucedidas e afirmam que gerações com falha e rejeições na moderação de conteúdo não são cobradas. A documentação de erros do AIHubMix recomenda consultar os registros de cobrança para verificar cobranças históricas; nenhuma cobrança por geração bem-sucedida ou com falha foi medida aqui.

Quanto tempo tenho para baixar um resultado do Flash?
Baixe-o imediatamente após a conclusão. O guia existente do Seedance 2.5 alerta que os URLs duram cerca de 30 minutos, mas o período exato de retenção do Flash não foi verificado, e um campo de expiração nulo não significa que o resultado seja permanente.

A saída MOV e os recursos de edição/extensão são compatíveis com o AIHubMix?
O esquema atual do Flash expõe os campos correspondentes em extra, e o fornecedor documenta esses recursos. Seu funcionamento de ponta a ponta pelo AIHubMix não foi verificado porque o teste de criação foi interrompido por uma resposta de cota insuficiente.

Continue lendo: a série Seedance 2.5 Flash

Fontes

Documentação e esquema verificados em 16 de novembro de 2026; respostas de validação registradas às 08:26 UTC. Os preços são estimativas oficiais da BytePlus, não cobranças medidas pelo gateway.

Um só gateway para vários provedores de IA. Feito para produção.

Acessar AIHubMix