Com uma imagem clara do produto, Claude Code e a API AIHubMix, você pode gerar referências de personagens no Seedream, registrá-las como ativos de pessoa virtual e usar o Seedance para criar um anúncio de produto de IA.
Este tutorial é baseado em uma campanha real de névoa de aloe e inclui a estrutura do projeto, configuração, comandos e um prompt de vídeo completo. O resultado alvo é um anúncio vertical de 20 segundos, 720p, 9:16 com uma pessoa e cenário gerados por IA.
Claude Code e AIHubMix alimentam todo o fluxo de trabalho. Claude Code lê o resumo do projeto, revisa os prompts e organiza a execução. AIHubMix fornece um ponto de entrada para o modelo, permitindo que a geração de imagens e vídeos opere dentro do mesmo projeto.
Os IDs dos modelos, parâmetros e tratamento de erros vêm de uma captura de projeto datada de 16 de setembro de 2026. Verifique a API atual antes de reutilizá-los. Os comandos usam o flow.py incluído e devem ser executados a partir da raiz do projeto.Baixe o Starter Completo
Baixe o código, prompts, configuração e imagens de exemplo
Após extrair, entre no diretório seedance-starter. O pacote inclui flow.py, dois snapshots de esquema, cinco arquivos de prompt, a imagem do produto e três imagens de referência. O script Python usa apenas a biblioteca padrão.
- Comece pela etapa de vídeo: use as três referências incluídas, configure sua chave e comece com a Etapa 4.
- Comece com seu próprio produto: substitua a imagem do produto e os detalhes do prompt, mova as imagens de referência incluídas para fora de
assets/, e comece com a Etapa 3.
Copie .env.example para .env e adicione sua própria chave de API. Sua conta precisa de acesso aos modelos relevantes, qualquer permissão de tarefa assíncrona necessária e cota suficiente. A geração da API incorrerá em cobranças de uso.
1. Prepare a Imagem do Produto e o Projeto
O produto de exemplo é Nature Republic Aloe Vera Mist. Ao adaptar o fluxo de trabalho, atualize a imagem, a descrição do produto e a ação de uso juntos.
| Arquivo | Propósito |
|---|---|
assets/product.png | Imagem original do produto |
prompts/prompt-a.txt | Prompt do retrato do personagem principal |
prompts/prompt-b.txt | Prompt do personagem segurando o produto |
prompts/prompt-c.txt | Prompt de uso do produto |
prompts/prompt-video.txt | Requisitos de linha do tempo, câmera e áudio do vídeo |
prompts.json | Dimensões, duração, dependências de referência e caminhos de prompt |
flow.py | Requisições de API, registro de ativos, polling e downloads |
seedream.schema.json, seedance.schema.json | Snapshots de esquema da API em cache |
Claude Code ajuda a ler o resumo do projeto e revisar a configuração e os prompts. flow.py envia as requisições reais através do AIHubMix.
Por que o AIHubMix se encaixa neste fluxo de trabalho
Um fluxo de trabalho de anúncio de produto de IA geralmente precisa de mais de um modelo. Um modelo de imagem cria as referências de pessoa e produto; um modelo de vídeo cria movimento e comportamento da câmera. O AIHubMix cobre a maioria dos modelos convencionais, permitindo que você selecione modelos por tarefa através de um único serviço de API, em vez de manter contas separadas, autenticação e pontos de entrada de requisição para cada fornecedor.
O AIHubMix também se conecta a vários fornecedores e seleciona automaticamente uma rota de baixa latência disponível. Isso pode reduzir o efeito da instabilidade de um único fornecedor em um fluxo de trabalho que deve completar a geração de imagens, processamento de ativos e geração de vídeos em sequência. A disponibilidade do modelo, roteamento e tempo de resposta ainda dependem das condições atuais do serviço.
Crie .env na raiz do projeto ou forneça a mesma variável em seu ambiente:
AIHUBMIX_API_KEY=replace_with_your_api_key
O projeto exclui .env através do .gitignore. Compartilhe apenas o nome da variável e um exemplo, nunca a chave real.
Todo o fluxo de trabalho começa com uma imagem clara do produto.
2. Defina o Alvo de Saída e Separe os Parâmetros de Imagem dos de Vídeo
A parte relevante de prompts.json se parece com isso. Mantenha o array stills e outros campos existentes ao editar o arquivo real.
{
"size": "1080x1920",
"aspect_ratio": "9:16",
"duration": 20,
"resolution": "720p",
"generate_audio": true,
"video_prompt_file": "prompts/prompt-video.txt"
}
size pertence à geração de imagem. aspect_ratio, duration, resolution e generate_audio pertencem à geração de vídeo. O script constrói requisições separadas em vez de enviar todo o objeto de configuração para ambos os endpoints.
O projeto usa estes IDs de modelo:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
Os snapshots de esquema incluídos mostram que o endpoint de imagem aceita size, enquanto o endpoint de vídeo aceita aspect_ratio. Misturá-los causa uma rejeição. flow.py verifica as propriedades do esquema em cache antes de enviar uma requisição, mas isso não é uma validação completa dos parâmetros.
3. Gere as Três Referências de Personagem na Ordem
Cada imagem tem um papel diferente, e as imagens posteriores dependem das anteriores:
| Referência | Conteúdo | Entradas |
|---|---|---|
| A: Retrato do personagem | Estabelecer rosto, cabelo, guarda-roupa, quarto e iluminação | Prompt de texto apenas neste exemplo |
| B: Segurando o produto | A mesma pessoa segura a garrafa com o rótulo voltado para a câmera | Imagem do produto + A |
| C: Usando o produto | A mesma pessoa pressiona a bomba do spray | Imagem do produto + B |
Os prompts repetem os detalhes do personagem e descrevem a forma, cores, layout do rótulo e manuseio natural do produto.
Execute:
python3 flow.py stills
Os resultados são salvos como assets/frame-01.jpg, frame-02.jpg e frame-03.jpg. Revise a consistência do personagem, a fidelidade da embalagem e o realismo da ação de uso.
O script ignora arquivos existentes. Se você alterar um prompt, faça backup e mova a saída correspondente antes de rerun. Alterar A pode também exigir regenerar B e C.
As referências estabelecem a identidade do personagem, a apresentação do produto e o uso do produto.
4. Hospede as Imagens e Registre Ativos de Retrato Virtual
O starter não contém nenhum ID de ativo da conta do autor. Registre as referências em sua própria conta.
Este projeto usa URLs de imagem públicas para registro. O fluxo de trabalho de origem usou URLs brutas do GitHub fixadas a um SHA de commit, mas qualquer hospedagem que retorne a imagem diretamente sem autenticação pode funcionar.
Uma URL do GitHub /blob/ retorna uma página HTML e não pode ser usada como uma URL de imagem.
Substitua este host de espaço reservado pela localização real de seus arquivos carregados:
IMAGE_BASE='https://your-public-image-host.example/campaign'
python3 flow.py check "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
python3 flow.py assets "$IMAGE_BASE/frame-01.jpg" "$IMAGE_BASE/frame-02.jpg" "$IMAGE_BASE/frame-03.jpg"
check verifica HTTP 200 e um Content-Type de imagem. assets cria ou reutiliza um grupo de ativos virtual_portrait, registra cada imagem, espera até que se torne active, e escreve os IDs dos ativos em state.json.
Esta etapa vem de uma falha real no projeto: passar URLs de personagens fotorealistas diretamente para o endpoint de vídeo retornou doubao_real_person_required. A pessoa nesta campanha foi gerada por IA, então virtual_portrait era a classificação correta. Uma fotografia de pessoa real deve seguir o processo de verificação correspondente e não deve ser rotulada como virtual.
Todos os ativos usados em uma requisição de vídeo devem pertencer ao mesmo grupo.
As referências foram geradas e todos os três ativos estavam ativos; a tarefa de vídeo ainda estava em execução quando esta captura de tela foi feita.
5. Escreva o Prompt de Vídeo como uma Linha do Tempo com Limites de Câmera
O prompt final do projeto divide uma tomada contínua de 20 segundos em quatro fases:
| Tempo | Ação do personagem | Posição do produto |
|---|---|---|
| 0–5 segundos | Olha para a câmera e apresenta a garrafa | Ao lado do rosto, rótulo voltado para a câmera |
| 5–10 segundos | Levanta a garrafa e pressiona a bomba | Permanece dentro do quadro |
| 10–15 segundos | Fecha os olhos e sente a névoa se assentar | Terço inferior do quadro |
| 15–20 segundos | Abre os olhos e apresenta o produto novamente | De volta ao lado do rosto, rótulo voltado para a câmera |
Um resultado anterior aproximou a câmera demais e perdeu o produto. Portanto, o prompt final limita o movimento a uma tomada média, exige que o produto permaneça visível e pede um rótulo legível durante os primeiros e últimos três segundos.
Uma tomada contínua de 20 segundos de um comercial de beleza vertical, sem cortes, em um canto minimalista iluminado pelo sol.
0-5s: a mesma mulher asiática oriental de 24 anos em uma camisa de linho verde-sálvia oversized sobre uma regata branca de malha se posiciona na penteadeira segurando o gel de névoa de aloe vera Nature Republic 92% Soothing Gel ao lado da bochecha, com o rótulo voltado para a câmera e totalmente legível. Ela olha para a câmera com um sorriso caloroso e fácil e gira ligeiramente a garrafa para que o rótulo pegue a luz da manhã.
5-10s: ela levanta a garrafa um pouco acima do nível dos olhos e pressiona a bomba de névoa fina. Um suave cone de névoa de aloe se espalha pelo rosto e captura a luz como um leve brilho de micro-gotas.
10-15s: seus olhos se fecham e seu queixo se levanta em um pequeno sorriso satisfeito enquanto a névoa se assenta, pequenas gotas repousando em seu osso da bochecha e sobrancelha. A garrafa permanece visível no terço inferior do quadro durante todo esse tempo.
15-20s: ela abre os olhos, traz a garrafa de volta ao lado da bochecha com o rótulo quadrado para a câmera e mantém um olhar final calmo para a lente.
Câmera: um movimento lento e suave de aproximação de uma moldura do peito para uma moldura média. Não ultrapasse uma tomada média. O produto deve permanecer dentro do quadro durante toda a tomada, e o rótulo deve ser claramente legível nos primeiros três segundos e nos últimos três segundos.
Aparência: luz suave e difusa da manhã vinda da esquerda da câmera, textura de pele fotorealista com real umidade na pele, névoa renderizada como spray genuinamente fotografado em vez de partículas digitais, publicidade premium de K-beauty. Mantenha a embalagem do produto, cores, materiais, layout do rótulo e texto do rótulo exatamente como nas imagens de referência; não redesenhe ou reescreva o produto. Sem sobreposições de texto, sem legendas, sem marcas d'água.
Áudio: um quarto silencioso e brilhante, um suave e curto hiss de spray, uma respiração suave. Sem música, sem narração.
A geração de áudio está habilitada, mas o prompt solicita apenas o tom do ambiente, um som de spray e uma respiração suave—sem música ou narração.
6. Gere e Salve o Vídeo
Após o registro do ativo, envie referências asset://. Este comando lê os IDs salvos e passa cada um como um argumento separado:
python3 - <<'PYCODE'
import json
import subprocess
import sys
from pathlib import Path
state = json.loads(Path("state.json").read_text())
refs = ["asset://" + asset_id for asset_id in state["asset_ids"]]
subprocess.run([sys.executable, "flow.py", "video", *refs], check=True)
PYCODE
Usar uma lista de argumentos também evita um problema do zsh no projeto de origem, onde vários IDs armazenados em uma única string simples poderiam chegar ao script como um argumento inválido.
O script salva o ID da tarefa de vídeo, faz polling até completed, e baixa a saída para out/video.mp4. Outro download pode sobrescrever esse caminho, então faça backup das versões que você deseja comparar.
Retome uma tarefa existente ou baixe novamente seu resultado com:
python3 flow.py status
Se a resposta de criação foi perdida, liste as tarefas recentes e retome o ID relevante:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Procurar uma tarefa existente antes de criar outra evita a geração acidental de duplicatas.
7. Revise a Saída e Itere
O projeto de origem mantém video-v1-10s.mp4 e o final video.mp4. A primeira versão durou apenas 10 segundos e não mostrou uso suficiente do produto, então o fluxo de trabalho passou por uma segunda iteração de prompt.
Revise cada resultado em relação a esta lista de verificação:
- [ ] Duração, resolução e proporção de aspecto correspondem ao alvo.
- [ ] O rosto, guarda-roupa e cenário do personagem permanecem consistentes.
- [ ] O produto permanece visível e seu rótulo pode ser lido no início e no final.
- [ ] As ações de manuseio e spray correspondem ao uso real do produto.
- [ ] A forma da garrafa, embalagem e texto não mudam visivelmente.
- [ ] A câmera não se aproxima demais, e o áudio corresponde ao pedido.
Se a duração estiver errada, inspecione tanto a configuração quanto a requisição real. Se o produto sair do quadro, fortaleça os limites da câmera. Se a ação de uso for muito curta, aloque tempo e comportamento de forma mais explícita. Editar apenas prompts/prompt-video.txt não requer regenerar imagens de referência; regenere e registre-as apenas quando as referências visuais precisarem mudar.
Perguntas Frequentes
Por que um nome de modelo que parece correto retorna 404?
O nome encurtado do Seedream retornou model_not_found no projeto de origem. Use o ID completo do modelo da API aceito pelo endpoint atual em vez de assumir que o nome de exibição de marketing também é o identificador da API.
Por que posso abrir uma imagem no meu navegador, mas ainda falho ao registrá-la?
Confirme que a URL retorna a imagem em si, em vez de HTML, uma página de compartilhamento ou uma página de login. Use python3 flow.py check URL... antes do registro.
Por que mudar um prompt não mudou a imagem de referência?
stills ignora arquivos existentes. Faça backup e mova qualquer imagem que precise ser regenerada, depois verifique se as referências a montante também devem ser regeneradas.
HTTP 200 significa que o vídeo está finalizado?
Não. O script ramifica-se no status da tarefa e baixa apenas após a tarefa atingir completed.
Comece Sua Primeira Versão
Prepare uma imagem do produto, configure o acesso ao AIHubMix e escolha os modelos de imagem e vídeo. Em seguida, deixe o Claude Code adaptar a descrição do produto e os prompts. Gere as três referências, revise e registre-as, crie o vídeo e use a lista de verificação para decidir a próxima iteração.
Quando um projeto futuro precisar de outro modelo, mantenha a mesma estrutura de arquivos e fluxo de trabalho, depois atualize a seleção de modelos do AIHubMix e os parâmetros específicos do modelo. Esse é o valor prático de um serviço de API unificado para uma equipe de conteúdo que usa vários modelos de IA: os modelos podem mudar por tarefa enquanto o fluxo de trabalho permanece reutilizável.
