/ai/v1/videos para gerar vídeos. Clientes que já usam /v1/videos podem consultar o exemplo do protocolo compatível.
Pré-requisitos
- Tenha uma API Key válida da AIHubMix e leia seu valor pela variável de ambiente
AIHUBMIX_API_KEY. - Antes de usar a nova API de vídeo, ative as tarefas assíncronas no console e confirme que a conta tem saldo suficiente e permissão para usar o modelo de destino.
- A pessoa retratada deve concordar com os usos previstos e concluir pessoalmente o processo de confirmação na página web. Adicione apenas materiais da mesma pessoa a um grupo.
- Prepare um link direto para a imagem que possa ser lido pelo provedor de modelos e permaneça válido durante o processamento do material.
- Os exemplos de linha de comando exigem Bash, curl e jq. Execute as etapas no mesmo terminal e guarde os IDs retornados do grupo de materiais, da sessão de confirmação, do material e da tarefa de vídeo.
O guia oficial da BytePlus para materiais de pessoas reais abrange Seedance 2.0 e Seedance 2.5. O exemplo principal da nova API de vídeo nesta página usa o ID de modelo da AIHubMix
doubao-seedance-2-5-260628, validado em produção; a versão específica, os tipos de mídia de referência e os parâmetros dependem do Schema atual do modelo e dos recursos disponíveis para a conta. Consulte o escopo em Validação deste fluxo e não presuma que todas as versões do Seedance aceitam materiais de pessoas reais.
- Criar um grupo de materiais
name, que não pode estar vazio e tem limite de 100 caracteres. A criação bem-sucedida retorna HTTP 201, com status inicial pending_auth.
Os campos públicos do grupo de materiais são id, object, name, status, created_at e updated_at. O valor de object é sempre asset_group, e os campos de tempo usam segundos Unix. Nas etapas seguintes, status=active indica que o grupo já permite adicionar materiais.
Se a resposta de criação for perdida, consulte primeiro a lista para evitar criar outro grupo diretamente:
data, has_more e next_after. Para obter a próxima página, envie after com o valor de next_after da página anterior; limit tem valor padrão 20 e máximo 100. O nome não funciona como identificador de idempotência; use o ID e o horário de criação para identificar o grupo de materiais.
- Obter o link de confirmação pessoal
Crie uma sessão de confirmação, sem corpo de requisição:
201. Os campos públicos são id, object, group_id, status, created_at, expires_at e completed_at; object é sempre verification_session, os campos de tempo usam segundos Unix e completed_at é null enquanto a sessão não estiver concluída.
A própria pessoa deve abrir verification_url, conferir a entidade e a finalidade exibidas na página, ler e aceitar os termos aplicáveis e concluir as operações conforme as instruções. O guia oficial da BytePlus informa que esse processo exige login em uma conta pessoal da BytePlus; quando a página solicitar permissão para a câmera, a própria pessoa deve operar o dispositivo e conceder a permissão.
A página oficial pode incluir etapas como o envio de materiais; siga as instruções exibidas. Ainda é necessário executar a próxima etapa de criação de materiais pela API desta página e obter o ID do material retornado pela AIHubMix; não substitua diretamente esse ID por outros IDs de materiais exibidos na página web.
- Consultar o resultado da confirmação
O cliente pode consultar a cada 10 a 15 segundos e definir um limite local de espera. Esse intervalo é uma recomendação de uso. Mesmo que a página web indique conclusão ou exiba uma página em branco, confirme pela API que a sessão está
verified e o grupo está active antes de adicionar materiais.
Se uma nova tentativa de criação retornar 409 verification_session_active, consulte primeiro a sessão existente e o grupo de materiais. Não crie sessões repetidamente quando ainda houver uma sessão válida, o grupo já tiver concluído a confirmação ou o resultado anterior ainda estiver aguardando confirmação. Se a situação persistir, contate o suporte.
- Criar um material a partir de uma URL de imagem
Preparação da imagem
Forneça uma URL HTTP(S) absoluta que retorne o arquivo de imagem, preferencialmente HTTPS. O link deve permitir leitura sem login nem cabeçalhos adicionais; caminhos locais, endereços de rede interna, Base64 e URLs com nome de usuário e senha não são aceitos pela API de criação de materiais. A URL não deve conter um fragmento#.
Segundo o guia da BytePlus para materiais de pessoas reais, recomenda-se uma foto frontal nítida que atenda aos seguintes requisitos de inclusão na biblioteca de materiais:
Esses são os requisitos oficiais da biblioteca de materiais; o modelo de vídeo pode impor restrições próprias aos materiais de referência. Confira também os requisitos do modelo de destino antes do envio; uma criação HTTP bem-sucedida não significa que o material já passou pelo processamento.
Requisição de criação
SubstituaIMAGE_URL pelo link direto de uma imagem cujo uso foi autorizado pela pessoa retratada. O domínio do exemplo é apenas um marcador e não fornece uma imagem de pessoa real.
O corpo da requisição aceita apenas os três campos acima.
Idempotency-Key é um cabeçalho opcional, com limite de 128 bytes, sem espaços em branco no início ou no fim nem caracteres de controle. Para os limites de arquivos de áudio e vídeo, consulte o guia oficial acima e confira os tipos e as durações aceitos pelo modelo de destino.
A primeira criação geralmente retorna HTTP 201; a reutilização de um material existente retorna 200; quando o resultado ainda aguarda confirmação e o status é reconciling, retorna 202. Sempre leia o status do objeto.
Os campos públicos do material são id, object, group_id, asset_type, status, client_reference_id, created_at, updated_at e deleted_at. object é sempre asset; client_reference_id não é retornado quando não foi fornecido ou foi excluído, e deleted_at é null enquanto o material não tiver sido excluído. Os campos de tempo usam segundos Unix. As consultas não retornam a URL original da imagem; mantenha seus próprios registros na aplicação.
- Aguardar a disponibilidade do material
Você pode consultar a cada 10 a 15 segundos e definir um limite local de espera. Interromper a consulta periódica local não cancela a operação no servidor.
- Gerar um vídeo usando o material
A referência de vídeo usa o id completo retornado pela AIHubMix na resposta de criação do material, no formato asset://<asset_id>. Todos os materiais referenciados na mesma requisição devem pertencer ao mesmo grupo e à conta atual, e todos devem estar active. O grupo de materiais também deve permanecer disponível.
O tipo de referência deve corresponder ao
asset_type usado na criação do material. asset:// é usado nos campos de referência de vídeo e não é uma URL para download pelo navegador.
Novo protocolo de vídeo
Primeiro, confira o Schema atual do modelo selecionando o caminho do endpoint:duration=4, resolution="480p", aspect_ratio="3:4" e generate_audio=false. A nova API usa diretamente input_references[].url, com ASSET_ID definido como o ID do material retornado anteriormente pela AIHubMix:
duration para indicar a duração solicitada; os demais valores permitidos dependem do Schema do modelo. resolution="480p" é a faixa de resolução solicitada e não garante largura ou altura fixa de 480 pixels na saída; as dimensões reais são as do arquivo gerado. Para os quadros inicial e final, use frame_images[].image_url.url e defina também frame_type, somente quando o modelo aceitar esse recurso. Consulte todos os parâmetros em Geração de vídeos.
Protocolo de vídeo compatível
Para clientes existentes que usam/v1/videos, coloque a referência em content ou extra_body.content, com a URL aninhada no objeto de mídia correspondente. Este exemplo usa extra_body.content:
O exemplo compatível mantém
doubao-seedance-2-0-260128 e foi elaborado com base no contrato existente da API compatível e nas instruções oficiais da BytePlus sobre referências a materiais. A geração de vídeos com Seedance 2.0 e a criação compatível por /v1/videos não foram testadas nesta execução; os resultados da validação do Seedance 2.5 na nova API não podem ser aplicados diretamente a este exemplo.input_references na requisição compatível. Se content for fornecido nos dois locais, extra_body.content substitui o content de nível superior; recomenda-se fornecê-lo em apenas um local.
Use o id retornado pela API compatível em GET /v1/videos/{id} para consultar e, após a conclusão, em GET /v1/videos/{id}/content para baixar. Não consulte IDs da API compatível em /ai/v1/videos. Veja os detalhes na API de vídeo compatível.
- Consultar periodicamente e baixar o vídeo da nova API
O exemplo Python abaixo dá continuidade apenas à etapa anterior de criação pela nova API, lê VIDEO_ID das variáveis de ambiente e não cria outra tarefa. É necessário instalar requests.
200 em uma consulta não significa geração bem-sucedida; é necessário verificar status. As consultas periódicas usam /ai/v1/videos/{id}; a API unificada de tarefas /ai/v1/tasks/{id} fornece um retrato somente leitura.
Use a mesma API Key da criação da tarefa para consultar e baixar o vídeo. Baixe e armazene o resultado assim que estiver concluído; os resultados têm prazo de retenção definido por expires_at e, após a expiração, podem retornar 410 artifact_expired.
Validação deste fluxo
A validação em produção de 2026-09-07 usou um link direto HTTPS público para um JPEG, a confirmação concluída pela própria pessoa na página web e os parâmetros do Seedance 2.5 acima, com os seguintes resultados observados:
O arquivo desta execução tinha 1,558,358 bytes; o ffprobe identificou H.264, 24 fps, 560 × 752 pixels, 4.041667 segundos e nenhuma faixa de áudio. Esses valores correspondem a esta geração e não significam que todas as requisições produzirão as mesmas dimensões, duração ou tamanho de arquivo.
Na primeira abertura da página de confirmação, foi exibido
internal error; a consulta posterior pela API ainda retornava pending, e a causa do erro da página não foi confirmada. Depois, o teste usou uma nova página de um grupo de teste independente e, após a própria pessoa concluir as operações, a sessão foi confirmada como verified e o grupo como active. O novo grupo foi apenas a abordagem adotada neste teste, sem constituir uma recomendação geral para recriar grupos repetidamente nem indicar que a sessão original terminou.
A geração de vídeos com Seedance 2.0, a criação pela API compatível, os materiais de áudio e vídeo, os quadros inicial e final, a exclusão e outras combinações de exceções não foram testados nesta execução. As respectivas descrições mantêm como base o contrato das APIs e a documentação oficial; esta validação não abrange todos os cenários do guia.
Novas tentativas idempotentes
- Se a criação de um material exceder o tempo limite ou a resposta for perdida, mantenha o
Idempotency-Key, oclient_reference_id, a URL e oasset_typeoriginais e reenvie a mesma requisição. Se qualquer um dos dois identificadores corresponder a um material existente da mesma conta e do mesmo grupo, esse material será reutilizado. - Se a URL ou o
asset_typeassociado ao mesmo identificador mudar, será retornado409 asset_idempotency_conflict. A atualização de uma URL de imagem assinada também conta como alteração de URL. - Sem nenhum dos identificadores, não há garantia de deduplicação entre requisições. Use um novo identificador somente quando tiver confirmado que deseja criar outro material.
- Após obter o ID do material, priorize a consulta por
GET /ai/v1/assets/{id}.reconcilingnão equivale a falha; não crie outro material com novos identificadores. - Após a conclusão da exclusão do material, os identificadores de idempotência originais deixam de ser mantidos. Não dependa deles para recuperar materiais excluídos nem reenvie requisições antigas de criação.
- As regras de idempotência desta seção se aplicam apenas à criação de materiais. Elas não se aplicam à criação de grupos de materiais, sessões de confirmação ou vídeos. Se a resposta de criação de vídeo na nova API for perdida, procure primeiro a tarefa original com
GET /ai/v1/videos?limit=20&order=descpara evitar geração duplicada.
Excluir materiais e grupos de materiais
Antes de excluir, confirme que todos os vídeos que referenciam o material foram finalizados, incluindo as tarefas enviadas pela API compatível. A exclusão não pode ser desfeita; os arquivos de vídeo já baixados devem ser gerenciados por você. Excluir um material individual:202 indica que a exclusão ainda está em andamento. Continue consultando por GET /ai/v1/assets/{id} até status=deleted. Repetir a exclusão retorna o status atual; se for reconciling, continue verificando o resultado e contate o suporte se a situação persistir.
A exclusão de todo o grupo também exclui os materiais contidos nele e exige o envio explícito de cascade=true:
202; consulte por GET /ai/v1/asset-groups/{id}. deleting indica processamento, partially_deleted indica que a exclusão ainda não está completa e somente deleted indica conclusão. Por padrão, a lista não exibe grupos de materiais excluídos.
409 asset_group_in_use indica que ainda existem operações ou tarefas de vídeo não finalizadas. Aguarde, consulte os status relacionados e tente novamente. Confirme por conta própria que as tarefas de vídeo compatíveis foram finalizadas; não dependa da requisição de exclusão para detectar automaticamente o uso por todas as tarefas compatíveis.
Perguntas frequentes
Por que ainda não consigo adicionar materiais após concluir as operações na página web?
Consulte primeiro a sessão de confirmação e o grupo de materiais, usandoverified e active como referência. Faça a mesma verificação se a página exibir internal error; enquanto o status for pending, não crie repetidamente sessões para o mesmo grupo. Se o resultado ainda não estiver confirmado, consulte novamente mais tarde; se a situação persistir, forneça os IDs ao suporte, sem enviar o link de confirmação nem fotos da pessoa.
Por que a geração de vídeo ainda falha quando o material está disponível?
Verifique se a referência usa o ID do material retornado pela AIHubMix, se todos os materiais pertencem ao mesmo grupo, se os tipos de mídia correspondem e se o modelo atual aceita as respectivas entradas. O statusactive indica disponibilidade do material; ainda é necessário verificar separadamente o status de conclusão e as mensagens de erro da tarefa de vídeo.
Como tratar os erros comuns da API?
Para outros erros de vídeo, consulte os códigos de erro de tarefas assíncronas. Ao enviar um relato, forneça o horário da ocorrência, o status HTTP,
error.code, o error.tid retornado (se houver) e os IDs dos recursos relacionados; não envie a API Key, o link de confirmação nem URLs de imagens assinadas.
Referências
- BytePlus: adicionar materiais de pessoas reais
- BytePlus: gerar vídeos de retrato com Seedance
- Geração nativa de vídeos da AIHubMix
- API de vídeo compatível com OpenAI
- Tarefas assíncronas