Con una imagen clara del producto, Claude Code y la API de AIHubMix, puedes generar referencias de personajes en Seedream, registrarlas como activos de persona virtual y usar Seedance para crear un anuncio de producto con IA.
Este tutorial se basa en una campaña real de bruma de aloe e incluye la estructura del proyecto, la configuración, los comandos y el prompt completo del video. El resultado objetivo es un anuncio vertical de 20 segundos, 720p, 9:16 con una persona y un escenario generados por IA.
Claude Code y AIHubMix impulsan todo el flujo de trabajo. Claude Code lee el resumen del proyecto, revisa los prompts y organiza la ejecución. AIHubMix proporciona un único punto de entrada al modelo, de modo que la generación de imágenes y de video puede funcionar dentro del mismo proyecto.
Los ID de modelo, los parámetros y el manejo de errores proceden de una instantánea del proyecto fechada el 16 de septiembre de 2026. Verifica la API actual antes de reutilizarlos. Los comandos usan el archivo incluido flow.py y deben ejecutarse desde la raíz del proyecto.Descarga el starter completo
Descarga el código, los prompts, la configuración y las imágenes de ejemplo:
https://drive.google.com/uc?export=download&id=1nXcj26Fq3daHeTd0SynS7_QEXgH8z4u_
Después de extraerlo, entra en el directorio seedance-starter. El paquete incluye flow.py, dos instantáneas de esquema, cinco archivos de prompt, la imagen del producto y tres imágenes de referencia. El script de Python solo usa la biblioteca estándar.
- Empieza por la etapa de video: usa las tres referencias incluidas, configura tu clave y comienza en el Paso 4.
- Empieza con tu propio producto: reemplaza la imagen del producto y los detalles del prompt, mueve las imágenes de referencia incluidas fuera de
assets/y comienza en el Paso 3.
Copia .env.example a .env y añade tu propia clave de API. Tu cuenta necesita acceso a los modelos correspondientes, el permiso de tareas asíncronas requerido y cuota suficiente. La generación mediante API genera cargos por uso.
1. Prepara la imagen del producto y el proyecto
El producto de ejemplo es Nature Republic Aloe Vera Mist. Al adaptar el flujo de trabajo, actualiza la imagen, la descripción del producto y la acción de uso en conjunto.
| Archivo | Finalidad |
|---|---|
assets/product.png | Imagen original del producto |
prompts/prompt-a.txt | Prompt del retrato del personaje principal |
prompts/prompt-b.txt | Prompt del personaje sosteniendo el producto |
prompts/prompt-c.txt | Prompt de uso del producto |
prompts/prompt-video.txt | Cronología del video, cámara y requisitos de audio |
prompts.json | Dimensiones, duración, dependencias de referencia y rutas de los prompts |
flow.py | Solicitudes a la API, registro de activos, sondeo y descargas |
seedream.schema.json, seedance.schema.json | Instantáneas en caché de los esquemas de la API |
Claude Code ayuda a leer el resumen del proyecto y a revisar la configuración y los prompts. flow.py envía las solicitudes reales a través de AIHubMix.
Por qué AIHubMix encaja en este flujo de trabajo
Un flujo de trabajo de anuncios de producto con IA suele necesitar más de un modelo. Un modelo de imagen crea las referencias de la persona y del producto; un modelo de video crea el movimiento y el comportamiento de la cámara. AIHubMix cubre la mayoría de los modelos principales, así que puedes seleccionar modelos según la tarea a través de un único servicio de API, en lugar de mantener cuentas, autenticación y puntos de entrada de solicitudes separados para cada proveedor.
AIHubMix también se conecta a varios proveedores y selecciona automáticamente una ruta disponible de baja latencia. Esto puede reducir el efecto de la inestabilidad de un solo proveedor en un flujo de trabajo que debe completar en secuencia la generación de imágenes, el procesamiento de activos y la generación de video. La disponibilidad de los modelos, el enrutamiento y el tiempo de respuesta siguen dependiendo de las condiciones actuales del servicio.
Crea .env en la raíz del proyecto, o define la misma variable en tu entorno:
AIHUBMIX_API_KEY=replace_with_your_api_key
El proyecto excluye .env mediante .gitignore. Comparte solo el nombre de la variable y el ejemplo, nunca la clave real.
Todo el flujo de trabajo comienza con una imagen clara del producto.
2. Define el objetivo de salida y separa los parámetros de imagen y de video
La parte relevante de prompts.json tiene este aspecto. Conserva el array stills existente y los demás campos al editar el archivo real.
{
"size": "1080x1920",
"aspect_ratio": "9:16",
"duration": 20,
"resolution": "720p",
"generate_audio": true,
"video_prompt_file": "prompts/prompt-video.txt"
}
size pertenece a la generación de imágenes. aspect_ratio, duration, resolution y generate_audio pertenecen a la generación de video. El script construye solicitudes separadas en lugar de enviar el objeto de configuración completo a ambos endpoints.
El proyecto usa estos ID de modelo:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
Las instantáneas de esquema incluidas muestran que el endpoint de imagen acepta size, mientras que el endpoint de video acepta aspect_ratio. Mezclarlos provoca un rechazo. flow.py comprueba las propiedades del esquema en caché antes de enviar una solicitud, pero esto no constituye una validación completa de parámetros.
3. Genera las tres referencias de personaje en orden
Cada imagen tiene un papel distinto, y las imágenes posteriores dependen de las anteriores:
| Referencia | Contenido | Entradas |
|---|---|---|
| A: Retrato del personaje | Establece el rostro, el cabello, el vestuario, la habitación y la iluminación | Solo prompt de texto en este ejemplo |
| B: Sosteniendo el producto | La misma persona sostiene el frasco con la etiqueta mirando a la cámara | Imagen del producto + A |
| C: Usando el producto | La misma persona presiona la bomba de pulverización | Imagen del producto + B |
Los prompts repiten los detalles del personaje y describen la forma del producto, sus colores, la disposición de la etiqueta y una manipulación natural.
Ejecuta:
python3 flow.py stills
Los resultados se guardan como assets/frame-01.jpg, frame-02.jpg y frame-03.jpg. Revisa la consistencia del personaje, la fidelidad del empaque y el realismo de la acción de uso.
El script omite los archivos existentes. Si cambias un prompt, haz una copia de seguridad y mueve la salida correspondiente antes de volver a ejecutarlo. Cambiar A también puede requerir regenerar B y C.
Las referencias establecen la identidad del personaje, la presentación del producto y el uso del producto.
4. Aloja las imágenes y registra los activos de retrato virtual
El starter no contiene ningún ID de activo de la cuenta del autor. Registra las referencias en tu propia cuenta.
Este proyecto usa URL públicas de imágenes para el registro. El flujo de trabajo original usaba URL raw de GitHub fijadas a un SHA de commit, pero cualquier alojamiento que devuelva la imagen directamente sin autenticación puede funcionar.
Una URL de GitHub con /blob/ devuelve una página HTML y no puede usarse como URL de imagen.
Reemplaza este host de marcador de posición por la ubicación real de tus archivos subidos:
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 y un Content-Type de imagen. assets crea o reutiliza un grupo de activos virtual_portrait, registra cada imagen, espera hasta que pase a active y escribe los ID de los activos en state.json.
Este paso proviene de un fallo real del proyecto: pasar URL de personajes fotorrealistas directamente al endpoint de video devolvió doubao_real_person_required. La persona de esta campaña fue generada por IA, por lo que virtual_portrait era la clasificación correcta. Una fotografía de una persona real debe seguir el proceso de verificación correspondiente y no debe etiquetarse como virtual.
Todos los activos usados en una misma solicitud de video deben pertenecer al mismo grupo.
Las referencias se generaron y los tres activos estaban activos; la tarea de video seguía en ejecución cuando se capturó esta captura de pantalla.
5. Escribe el prompt del video como una cronología con límites de cámara
El prompt final del proyecto divide un plano continuo de 20 segundos en cuatro fases:
| Tiempo | Acción del personaje | Posición del producto |
|---|---|---|
| 0–5 segundos | Mira a la cámara y presenta el frasco | Junto a su rostro, etiqueta hacia la cámara |
| 5–10 segundos | Levanta el frasco y presiona la bomba | Permanece dentro del encuadre |
| 10–15 segundos | Cierra los ojos y siente la bruma asentarse | Tercio inferior del encuadre |
| 15–20 segundos | Abre los ojos y vuelve a presentar el producto | De nuevo junto a su rostro, etiqueta hacia la cámara |
Un resultado anterior acercó demasiado la cámara y perdió el producto. Por ello, el prompt final limita el movimiento a un plano medio cercano, exige que el producto permanezca visible y pide una etiqueta legible durante los primeros y los últimos tres segundos.
Aquí está el prompts/prompt-video.txt completo. Para otro producto, actualiza la marca, la descripción del empaque y la acción de uso. Estas instrucciones son objetivos de generación y aún requieren revisión del 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.
La generación de audio está activada, pero el prompt solo solicita el ambiente de la habitación, un sonido de pulverización y una respiración suave, sin música ni voz en off.
6. Genera y guarda el video
Después del registro de activos, envía las referencias asset://. Este comando lee los ID guardados y pasa cada uno como un 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 una lista de argumentos también evita un problema de zsh del proyecto original, en el que varios ID almacenados en una cadena simple podían llegar al script como un único argumento no válido.
El script guarda el ID de la tarea de video, sondea hasta que completed y descarga la salida en out/video.mp4. Otra descarga puede sobrescribir esa ruta, así que haz copias de seguridad de las versiones que quieras comparar.
Para reanudar una tarea existente o volver a descargar su resultado, usa:
python3 flow.py status
Si se perdió la respuesta de creación, lista las tareas recientes y reanuda el ID correspondiente:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Buscar una tarea existente antes de crear otra evita la generación duplicada accidental.
7. Revisa el resultado e itera
El proyecto original conserva video-v1-10s.mp4 y el video.mp4 final. La primera versión duraba solo 10 segundos y no mostraba suficiente uso del producto, por lo que el flujo de trabajo pasó por una segunda iteración del prompt.
Revisa cada resultado con esta lista de verificación:
- [ ] La duración, la resolución y la relación de aspecto coinciden con el objetivo.
- [ ] El rostro, el vestuario y el escenario del personaje se mantienen consistentes.
- [ ] El producto permanece visible y su etiqueta se puede leer al inicio y al final.
- [ ] La manipulación y la acción de pulverizar coinciden con el uso real del producto.
- [ ] La forma del frasco, el empaque y el texto no cambian de forma notable.
- [ ] La cámara no se acerca demasiado y el audio coincide con lo solicitado.
Si la duración es incorrecta, revisa tanto la configuración como la solicitud real. Si el producto sale del encuadre, refuerza los límites de cámara. Si la acción de uso es demasiado corta, asigna el tiempo y el comportamiento de forma más explícita. Editar solo prompts/prompt-video.txt no requiere regenerar las imágenes de referencia; regénéralas y regístralas solo cuando cambien las referencias visuales.
Preguntas frecuentes
¿Por qué un nombre de modelo que parece correcto devuelve un error 404?
El nombre abreviado de Seedream devolvió model_not_found en el proyecto de origen. Usa el ID completo del modelo de API aceptado por el endpoint actual, en lugar de suponer que el nombre comercial también es el identificador de la API.
¿Por qué puedo abrir una imagen en mi navegador pero aun así falla su registro?
Confirma que la URL devuelve la imagen en sí y no HTML, una página de compartir o una página de inicio de sesión. Usa python3 flow.py check URL... antes del registro.
¿Por qué cambiar un prompt no cambió la imagen de referencia?
stills omite los archivos existentes. Haz una copia de seguridad y mueve cualquier imagen que necesite regenerarse, y luego comprueba si las referencias posteriores también deben regenerarse.
¿Un HTTP 200 significa que el video está terminado?
No. El script se basa en el status de la tarea y descarga el archivo solo cuando la tarea alcanza completed.
Empieza tu primera versión
Prepara una imagen de producto, configura el acceso a AIHubMix y elige los modelos de imagen y video. Después, deja que Claude Code adapte la descripción del producto y los prompts. Genera las tres referencias, revísalas y regístralas, crea el video y usa la lista de verificación para decidir la siguiente iteración.
Cuando un proyecto futuro necesite otro modelo, mantén la misma estructura de archivos y el mismo flujo de trabajo, y luego actualiza la selección de modelos de AIHubMix y los parámetros específicos de cada modelo. Ahí está el valor práctico de un servicio de API unificado para un equipo de contenido que usa varios modelos de IA: los modelos pueden cambiar según la tarea mientras el flujo de trabajo sigue siendo reutilizable.
