Com uma imagem clara do produto, o Claude Code e a API do AIHubMix, você pode gerar referências de personagem no Seedream, registrá-las como ativos de pessoa virtual e usar o Seedance para criar um anúncio de produto com IA.
Este tutorial é baseado em uma campanha real de névoa de aloe vera e inclui a estrutura do projeto, a configuração, os comandos e o prompt completo do vídeo. O resultado esperado é um anúncio vertical de 20 segundos, 720p, 9:16, com uma pessoa e um cenário gerados por IA.
O Claude Code e o AIHubMix alimentam todo o fluxo de trabalho. O Claude Code lê o briefing do projeto, revisa os prompts e organiza a execução. O AIHubMix fornece um único ponto de entrada de modelos, para que a geração de imagens e vídeos funcione dentro do mesmo projeto.
Os IDs de modelo, parâmetros e o tratamento de erros vêm de um snapshot do projeto datado 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, os prompts, a configuração e as imagens de exemplo:
https://drive.google.com/uc?export=download&id=1nXcj26Fq3daHeTd0SynS7_QEXgH8z4u_
Depois de extrair o arquivo, entre no diretório seedance-starter. O pacote inclui flow.py, dois snapshots de schema, 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 pelo Passo 4.
- Comece com o 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 pelo Passo 3.
Copie .env.example para .env e adicione sua própria chave de API. Sua conta precisa ter acesso aos modelos relevantes, a qualquer permissão necessária para tarefas assíncronas e cota suficiente. A geração via API gera cobranças de uso.
1. Prepare a imagem do produto e o projeto
O produto de exemplo é a Névoa de Aloe Vera da Nature Republic. Ao adaptar o fluxo de trabalho, atualize a imagem, a descrição do produto e a ação de uso em conjunto.
| Arquivo | Finalidade |
|---|---|
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 | Linha do tempo do vídeo, requisitos de câmera e áudio |
prompts.json | Dimensões, duração, dependências de referência e caminhos dos prompts |
flow.py | Requisições à API, registro de ativos, polling e downloads |
seedream.schema.json, seedance.schema.json | Snapshots em cache dos schemas da API |
O Claude Code ajuda a ler o briefing do projeto e a revisar a configuração e os prompts. O flow.py envia as requisições reais pelo AIHubMix.
Por que o AIHubMix se encaixa neste fluxo de trabalho
Um fluxo de anúncios de produto com IA geralmente precisa de mais de um modelo. Um modelo de imagem cria as referências da pessoa e do produto; um modelo de vídeo cria o movimento e o comportamento da câmera. O AIHubMix cobre a maioria dos modelos mais usados, então você pode escolher modelos por tarefa por meio de um único serviço de API, em vez de manter contas, autenticações e pontos de entrada separados para cada provedor.
O AIHubMix também se conecta a vários fornecedores e seleciona automaticamente uma rota disponível de baixa latência. Isso pode reduzir o efeito da instabilidade de um único fornecedor em um fluxo que precisa concluir, em sequência, a geração de imagens, o processamento de ativos e a geração de vídeo. A disponibilidade dos modelos, o roteamento e o tempo de resposta ainda dependem das condições atuais do serviço.
Crie um .env na raiz do projeto ou forneça a mesma variável no seu ambiente:
AIHUBMIX_API_KEY=replace_with_your_api_key
O projeto exclui o .env por meio do .gitignore. Compartilhe apenas o nome da variável e o exemplo, nunca a chave real.
Todo o fluxo de trabalho começa com uma imagem clara do produto.
2. Defina o resultado esperado e separe os parâmetros de imagem e vídeo
A parte relevante do prompts.json tem esta aparência. Mantenha o array stills existente e os demais campos 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 imagens. aspect_ratio, duration, resolution e generate_audio pertencem à geração de vídeo. O script monta requisições separadas em vez de enviar o objeto de configuração inteiro para os dois endpoints.
O projeto usa estes IDs de modelo:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
Os snapshots de schema incluídos mostram que o endpoint de imagem aceita size, enquanto o endpoint de vídeo aceita aspect_ratio. Misturá-los causa rejeição. O flow.py verifica as propriedades do schema 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 em ordem
Cada imagem tem um papel diferente, e as imagens posteriores dependem das anteriores:
| Referência | Conteúdo | Entradas |
|---|---|---|
| A: Retrato do personagem | Estabelece rosto, cabelo, figurino, ambiente e iluminação | Apenas prompt de texto neste exemplo |
| B: Segurando o produto | A mesma pessoa segura o frasco com o rótulo voltado para a câmera | Imagem do produto + A |
| C: Usando o produto | A mesma pessoa pressiona o spray | Imagem do produto + B |
Os prompts repetem os detalhes do personagem e descrevem o formato, as cores e a disposição do rótulo do produto, além do manuseio natural.
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 que já existem. Se você alterar um prompt, faça backup e mova a saída correspondente antes de executar novamente. Alterar A também pode exigir a regeneração de 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 os ativos de retrato virtual
O starter não contém nenhum ID de ativo da conta do autor. Registre as referências na sua própria conta.
Este projeto usa URLs públicas de imagens para o registro. O fluxo original usou URLs raw do GitHub fixadas em um SHA de commit, mas qualquer hospedagem que retorne a imagem diretamente, sem autenticação, pode funcionar.
Uma URL /blob/ do GitHub retorna uma página HTML e não pode ser usada como URL de imagem.
Substitua este host de exemplo pelo local real dos seus arquivos enviados:
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, aguarda até que ela fique active e grava os IDs dos ativos em state.json.
Esta etapa vem de uma falha real no projeto: passar URLs de personagens fotorrealistas diretamente para o endpoint de vídeo retornou doubao_real_person_required. A pessoa desta 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 pode 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 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 do vídeo como uma linha do tempo com limites de câmera
O prompt final do projeto divide um único plano contínuo 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 o frasco | Ao lado do rosto, rótulo voltado para a câmera |
| 5–10 segundos | Ergue o frasco e pressiona o spray | Permanece dentro do quadro |
| 10–15 segundos | Fecha os olhos e sente a névoa 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 demais a câmera e perdeu o produto. O prompt final, portanto, limita o movimento a um plano médio-fechado, exige que o produto permaneça visível e pede um rótulo legível nos primeiros e nos últimos três segundos.
Aqui está o prompts/prompt-video.txt completo. Para outro produto, atualize a marca, a descrição da embalagem e a ação de uso. Estas instruções são alvos de geração e ainda exigem revisão do resultado.
One continuous 20-second vertical beauty commercial take, no cuts, in a sunlit minimalist vanity corner.
0-5s: the same 24-year-old East Asian woman in an oversized sage-green linen shirt over a white ribbed tank top stands at the vanity holding the translucent light-green Nature Republic Aloe Vera 92% Soothing Gel Mist beside her cheek, the label facing camera and fully legible. She looks to camera with a warm, easy smile and turns the bottle slightly so the label catches the morning light.
5-10s: she lifts the bottle just above eye level and presses the fine-mist pump. A soft cone of aloe mist sprays across her face and catches the light as a faint sparkle of micro-droplets.
10-15s: her eyes close and her chin lifts into a small contented smile as the mist settles, tiny droplets resting on her cheekbone and brow. The bottle stays visible in the lower third of the frame throughout this beat.
15-20s: she opens her eyes, brings the bottle back up beside her cheek with the label square to camera, and holds a final calm look at the lens.
Camera: one slow, smooth push-in from a chest-up framing to a mid-close framing ONLY. Do not push past a mid-close shot. The product must stay inside the frame for the entire take, and the label must be clearly legible in both the first three seconds and the last three seconds.
Look: soft diffused morning sunlight from camera left, photorealistic skin texture with real moisture on the skin, mist rendered as genuinely photographed spray rather than digital particles, premium K-beauty advertising. Keep the product packaging, colours, materials, label layout and label text exactly as in the reference images; do not redesign or re-letter the product. No text overlays, no captions, no watermarks.
Audio: a quiet bright room, one soft short pump-spray hiss, a gentle breath. No music, no voiceover.
A geração de áudio está ativada, mas o prompt pede apenas o ambiente sonoro da sala, um som de spray e uma respiração suave, sem música nem narração.
6. Gere e salve o vídeo
Após o registro dos ativos, envie as 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 do projeto original, em que vários IDs armazenados em uma única string podiam chegar ao script como um único argumento inválido.
O script salva o ID da tarefa de vídeo, consulta o status 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ê quer comparar.
Para retomar uma tarefa existente ou baixar novamente o resultado, use:
python3 flow.py status
Se a resposta de criação foi perdida, liste as tarefas recentes e retome o ID correspondente:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Procurar uma tarefa existente antes de criar outra evita gerações duplicadas acidentais.
7. Revise o resultado e itere
O projeto original mantém o video-v1-10s.mp4 e o video.mp4 final. A primeira versão durou apenas 10 segundos e não mostrou uso suficiente do produto, então o fluxo passou por uma segunda iteração do prompt.
Revise cada resultado com esta lista de verificação:
- [ ] A duração, a resolução e a proporção correspondem ao alvo.
- [ ] O rosto, o figurino e o cenário do personagem permanecem consistentes.
- [ ] O produto permanece visível e o rótulo pode ser lido no início e no fim.
- [ ] As ações de manuseio e de spray correspondem ao uso real do produto.
- [ ] O formato do frasco, a embalagem e o texto não mudam de forma perceptível.
- [ ] A câmera não se aproxima demais e o áudio corresponde ao que foi solicitado.
Se a duração estiver errada, verifique tanto a configuração quanto a requisição real. Se o produto sair do quadro, reforce os limites de câmera. Se a ação de uso for curta demais, defina o tempo e o comportamento de forma mais explícita. Editar somente prompts/prompt-video.txt não exige regenerar as 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 abreviado do Seedream retornou model_not_found no projeto de origem. Use o ID completo do modelo de API aceito pelo endpoint atual, em vez de presumir que o nome comercial exibido também é o identificador da API.
Por que consigo abrir uma imagem no navegador, mas ainda assim falho ao registrá-la?
Confirme que a URL retorna a própria imagem, e não HTML, uma página de compartilhamento ou uma página de login. Use python3 flow.py check URL... antes do registro.
Por que alterar um prompt não mudou a imagem de referência?
stills ignora arquivos que já existem. Faça backup e mova qualquer imagem que precise ser regenerada e, em seguida, verifique se as referências dependentes também devem ser regeneradas.
HTTP 200 significa que o vídeo está pronto?
Não. O script verifica o status da tarefa e faz o download somente depois que a tarefa atinge completed.
Comece sua primeira versão
Prepare uma imagem do produto, configure o acesso ao AIHubMix e escolha os modelos de imagem e de 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 checklist para decidir a próxima iteração.
Quando um projeto futuro precisar de outro modelo, mantenha a mesma estrutura de arquivos e o mesmo fluxo de trabalho e, depois, atualize a seleção de modelos no AIHubMix e os parâmetros específicos de cada 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 conforme a tarefa, enquanto o fluxo de trabalho continua reutilizável.
