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:
- Ative as tarefas de mídia assíncronas no console do AIHubMix. O erro documentado para contas sem esse recurso é
403 async_not_enabled. - 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_quotacom a mensagemYour account has insufficient quota. Add credits and try again. - Exporte
AIHUBMIX_API_KEYno shell. Não inclua a chave em arquivos-fonte nem em código executado no navegador. - 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 valoresauto,reference,editeextendparaextra.omni_reference_task_type. Se você enviar explicitamente o campo de tipo de tarefa, o esquema exigeinput_referencesnão vazio.edittambém exige uma referência de vídeo, proporção adaptável eduration: -1;extendexige 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.TaskTypeConstraintassíncrono quando o tipo de tarefa inferido entra em conflito com os parâmetros, eInvalidParameter.TaskTypeMismatchquando o tipo inferido difere daquele solicitado explicitamente. O mapeamento exato no AIHubMix não foi medido; inspecione oerrorretornado 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
draftedraft_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_identifiereextra.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 listapriorityetoolspara 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/videose 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
- Precisa comparar preços e avaliar as diferenças de resolução antes de escolher um modelo? Seedance 2.5 Flash vs 2.5 e 2.0: vale a pena fazer o upgrade?
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.
- API de geração de vídeo (documentação do AIHubMix)
- API de tarefas assíncronas (documentação do AIHubMix)
- Guia de ativos de pessoas reais do Doubao (documentação do AIHubMix)
- Preços do ModelArk (BytePlus)
- Tutorial do Seedance 2.5 (Volcengine Ark)



