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 de IA.
Este tutorial se basa en una campaña real de aloe en spray e incluye la estructura del proyecto, configuración, comandos y un aviso de video completo. La salida objetivo es un anuncio vertical de 20 segundos, 720p, 9:16 con una persona y un entorno generados por IA.
Claude Code y AIHubMix impulsan todo el flujo de trabajo. Claude Code lee el resumen del proyecto, revisa los avisos y organiza la ejecución. AIHubMix proporciona un punto de entrada de modelo para que la generación de imágenes y videos pueda operar dentro del mismo proyecto.
Los IDs de modelo, parámetros y manejo de errores provienen de una instantánea del proyecto fechada el 16 de septiembre de 2026. Consulta la API actual antes de reutilizarlos. Los comandos utilizan el flow.py incluido y deben ejecutarse desde la raíz del proyecto.Descargar el Starter Completo
Descarga el código, avisos, configuración e imágenes de muestra
Después de extraerlo, ingresa al directorio seedance-starter. El paquete incluye flow.py, dos instantáneas de esquema, cinco archivos de aviso, la imagen del producto y tres imágenes de referencia. El script de Python utiliza solo la biblioteca estándar.
- Comienza con la etapa de video: usa las tres referencias incluidas, configura tu clave y comienza con el Paso 4.
- Comienza con tu propio producto: reemplaza la imagen del producto y los detalles del aviso, mueve las imágenes de referencia incluidas fuera de
assets/, y comienza con el Paso 3.
Copia .env.example a .env y agrega tu propia clave API. Tu cuenta necesita acceso a los modelos relevantes, cualquier permiso de tarea asíncrona requerido y suficiente cuota. La generación de API incurre en 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 juntos.
| Archivo | Propósito |
|---|---|
assets/product.png | Imagen original del producto |
prompts/prompt-a.txt | Aviso del retrato del personaje principal |
prompts/prompt-b.txt | Aviso del personaje sosteniendo el producto |
prompts/prompt-c.txt | Aviso de uso del producto |
prompts/prompt-video.txt | Línea de tiempo del video, cámara y requisitos de audio |
prompts.json | Dimensiones, duración, dependencias de referencia y rutas de aviso |
flow.py | Solicitudes de API, registro de activos, sondeo y descargas |
seedream.schema.json, seedance.schema.json | Instantáneas de esquema de API en caché |
Claude Code ayuda a leer el resumen del proyecto y revisar la configuración y los avisos. flow.py envía las solicitudes reales a través de AIHubMix.
Por qué AIHubMix se adapta a este flujo de trabajo
Un flujo de trabajo de anuncio de producto de IA generalmente necesita más de un modelo. Un modelo de imagen crea las referencias de persona y producto; un modelo de video crea movimiento y comportamiento de cámara. AIHubMix cubre la mayoría de los modelos convencionales, por lo que puedes seleccionar modelos por tarea a través de un servicio de API en lugar de mantener cuentas separadas, autenticación y puntos de entrada de solicitud para cada proveedor.
AIHubMix también se conecta a múltiples proveedores y selecciona automáticamente una ruta de baja latencia disponible. Esto puede reducir el efecto de la inestabilidad de un solo proveedor en un flujo de trabajo que debe completar la generación de imágenes, el procesamiento de activos y la generación de videos en secuencia. La disponibilidad del modelo, el enrutamiento y el tiempo de respuesta aún dependen de las condiciones actuales del servicio.
Crea .env en la raíz del proyecto, o proporciona la misma variable en tu entorno:
AIHUBMIX_API_KEY=replace_with_your_api_key
El proyecto excluye .env a través de .gitignore. Comparte solo el nombre de la variable y un ejemplo, nunca la clave real.
Todo el flujo de trabajo comienza con una imagen clara del producto.
2. Establecer el Objetivo de Salida y Separar Parámetros de Imagen de Video
La parte relevante de prompts.json se ve así. Mantén el array stills y otros campos existentes 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 todo el objeto de configuración a ambos puntos finales.
El proyecto utiliza estos IDs de modelo:
- Seedream:
doubao-seedream-5-0-pro-260628 - Seedance:
doubao-seedance-2-5-260628
Las instantáneas de esquema empaquetadas muestran que el punto final de imagen acepta size, mientras que el punto final de video acepta aspect_ratio. Mezclarlos causa un rechazo. flow.py verifica las propiedades del esquema en caché antes de enviar una solicitud, pero esto no es una validación completa de parámetros.
3. Generar las Tres Referencias de Personajes en Orden
Cada imagen tiene un rol diferente, y las imágenes posteriores dependen de las anteriores:
| Referencia | Contenido | Entradas |
|---|---|---|
| A: Retrato del personaje | Establecer cara, cabello, vestuario, habitación y luz | Solo aviso de texto en este ejemplo |
| B: Sosteniendo el producto | La misma persona sostiene la botella con la etiqueta frente a la cámara | Imagen del producto + A |
| C: Usando el producto | La misma persona presiona la bomba de spray | Imagen del producto + B |
Los avisos repiten los detalles del personaje y describen la forma del producto, colores, diseño de la etiqueta y manejo 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 archivos existentes. Si cambias un aviso, haz una copia de seguridad y mueve la salida correspondiente antes de volver a ejecutar. 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. Alojar las Imágenes y Registrar Activos de Retrato Virtual
El starter no contiene ID de activo de la cuenta del autor. Registra las referencias en tu propia cuenta.
Este proyecto utiliza URLs de imagen públicas para el registro. El flujo de trabajo de origen utilizó URLs en crudo 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 /blob/ devuelve una página HTML y no puede usarse como URL de imagen.
Reemplaza este host de marcador de posición con 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 se vuelva active, y escribe los IDs de activos en state.json.
Este paso proviene de un fallo real en el proyecto: pasar URLs de personajes fotorealistas directamente al punto final de video devolvió doubao_real_person_required. La persona en esta campaña fue generada por IA, por lo que virtual_portrait fue 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 utilizados en una solicitud de video deben pertenecer al mismo grupo.
Las referencias fueron generadas y los tres activos estaban activos; la tarea de video aún se estaba ejecutando cuando se capturó esta captura de pantalla.
5. Escribir el Aviso de Video como una Línea de Tiempo con Límites de Cámara
El aviso final del proyecto divide una toma continua 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 la botella | Junto a su cara, etiqueta hacia la cámara |
| 5–10 segundos | Levanta la botella y presiona la bomba | Permanece dentro del marco |
| 10–15 segundos | Cierra los ojos y siente la bruma asentarse | Tercio inferior del marco |
| 15–20 segundos | Abre los ojos y presenta el producto nuevamente | De regreso junto a su cara, etiqueta hacia la cámara |
Un resultado anterior acercó demasiado la cámara y perdió el producto. Por lo tanto, el aviso final limita el movimiento a una toma media-cercana, requiere que el producto permanezca visible y pide que la etiqueta sea legible durante los primeros y últimos tres segundos.
Aquí está el completo prompts/prompt-video.txt. 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 de salida.
Una toma continua de 20 segundos de un comercial de belleza vertical, sin cortes, en una esquina de tocador minimalista iluminada por el sol.
0-5s: la misma mujer asiática oriental de 24 años con una camisa de lino verde salvia de gran tamaño sobre una camiseta blanca de canalé sostiene el gel de aloe vera Nature Republic 92% Soothing Gel Mist de color verde claro translúcido junto a su mejilla, la etiqueta frente a la cámara y completamente legible. Ella mira a la cámara con una cálida y fácil sonrisa y gira ligeramente la botella para que la etiqueta capte la luz de la mañana.
5-10s: levanta la botella justo por encima del nivel de los ojos y presiona la bomba de spray fino. Un suave cono de bruma de aloe se rocía sobre su rostro y capta la luz como un leve destello de microgotas.
10-15s: sus ojos se cierran y su barbilla se levanta en una pequeña sonrisa de satisfacción mientras la bruma se asienta, pequeñas gotas descansando sobre su pómulo y frente. La botella permanece visible en el tercio inferior del marco durante este momento.
15-20s: abre los ojos, vuelve a llevar la botella junto a su mejilla con la etiqueta cuadrada hacia la cámara y sostiene una última mirada tranquila hacia el lente.
Cámara: un suave y lento acercamiento desde un encuadre de pecho hacia un encuadre medio-cercano SOLAMENTE. No acerques más allá de una toma media-cercana. El producto debe permanecer dentro del marco durante toda la toma, y la etiqueta debe ser claramente legible en los primeros tres segundos y en los últimos tres segundos.
Apariencia: suave luz de mañana difusa desde la izquierda de la cámara, textura de piel fotorealista con verdadera humedad en la piel, bruma representada como spray genuinamente fotografiado en lugar de partículas digitales, publicidad premium de K-beauty. Mantén el empaque del producto, colores, materiales, diseño de etiqueta y texto de etiqueta exactamente como en las imágenes de referencia; no rediseñes ni reescribas el producto. Sin superposiciones de texto, sin subtítulos, sin marcas de agua.
Audio: una habitación tranquila y brillante, un suave y corto sonido de spray, una suave respiración. Sin música, sin voz en off.
La generación de audio está habilitada, pero el aviso solicita solo el tono de la habitación, un sonido de spray y una suave respiración—sin música ni voz en off.
6. Generar y Guardar el Video
Después del registro de activos, envía referencias asset://. Este comando lee los IDs 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 fuente, donde varios IDs almacenados en una sola cadena de texto simple podrían llegar al script como un argumento inválido.
El script guarda el ID de tarea de video, sondea hasta que esté completed, y descarga la salida a out/video.mp4. Otra descarga puede sobrescribir esa ruta, así que haz copias de seguridad de las versiones que quieras comparar.
Reanuda una tarea existente o vuelve a descargar su resultado con:
python3 flow.py status
Si la respuesta de creación se perdió, lista las tareas recientes y reanuda el ID relevante:
python3 flow.py tasks
python3 flow.py status VIDEO_TASK_ID
Buscar una tarea existente antes de crear otra evita la generación accidental de duplicados.
7. Revisar la Salida e Iterar
El proyecto fuente mantiene video-v1-10s.mp4 y el final video.mp4. La primera versión duró solo 10 segundos y no mostró suficiente uso del producto, por lo que el flujo de trabajo pasó por una segunda iteración de aviso.
Revisa cada resultado contra esta lista de verificación:
- [ ] La duración, resolución y relación de aspecto coinciden con el objetivo.
- [ ] La cara, vestuario y entorno del personaje permanecen consistentes.
- [ ] El producto permanece visible y su etiqueta puede leerse al principio y al final.
- [ ] Las acciones de manejo y spray coinciden con el uso real del producto.
- [ ] La forma de la botella, el empaque y el texto no cambian notablemente.
- [ ] La cámara no se mueve demasiado cerca, y el audio coincide con la solicitud.
Si la duración es incorrecta, inspecciona tanto la configuración como la solicitud real. Si el producto sale del marco, refuerza los límites de la cámara. Si la acción de uso es demasiado corta, asigna tiempo y comportamiento de manera más explícita. Editar solo prompts/prompt-video.txt no requiere regenerar imágenes de referencia; regénéralos y regístralos solo cuando las referencias visuales deban cambiar.
Preguntas Frecuentes
¿Por qué un nombre de modelo que parece correcto devuelve 404?
El nombre abreviado de Seedream devolvió model_not_found en el proyecto fuente. Utiliza el ID de modelo de API completo aceptado por el punto final actual en lugar de asumir que el nombre de exhibición de marketing también es el identificador de API.
¿Por qué puedo abrir una imagen en mi navegador pero aún así no puedo registrarla?
Confirma que la URL devuelve la imagen en sí en lugar de 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 aviso no cambió la imagen de referencia?
stills omite archivos existentes. Haz una copia de seguridad y mueve cualquier imagen que necesite regeneración, luego verifica si las referencias posteriores también deben regenerarse.
¿HTTP 200 significa que el video ha terminado?
No. El script se bifurca según el status de la tarea y descarga solo después de que la tarea alcanza completed.
Comienza Tu Primera Versión
Prepara una imagen del producto, configura el acceso a AIHubMix y elige los modelos de imagen y video. Luego deja que Claude Code adapte la descripción del producto y los avisos. Genera las tres referencias, revísalas y regístralas, crea el video y utiliza la lista de verificación para decidir la próxima iteración.
Cuando un proyecto futuro necesite otro modelo, mantén la misma estructura de archivos y flujo de trabajo, luego actualiza la selección de modelos de AIHubMix y los parámetros específicos del modelo. Ese es el valor práctico de un servicio de API unificado para un equipo de contenido que utiliza varios modelos de IA: los modelos pueden cambiar según la tarea mientras que el flujo de trabajo sigue siendo reutilizable.
