VideoMakerStudio - Higgsfield AI

Higgsfield Generate (Traducción al español)

Envía trabajos a cualquier modelo de Higgsfield. Envuelve la CLI de higgsfield. Cubre generación genérica de imágenes/videos, Marketing Studio (anuncios con marca, avatares, productos, ganchos, configuraciones) y, secundariamente, la puntuación de videos con Virality Predictor.

Paso 0 — Arranque

Antes de cualquier otro comando:

1. Si higgsfield no está en $PATH, instálalo:

   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   

2. Si higgsfield account status falla con Session expired / Not authenticated, pide al usuario que ejecute higgsfield auth login (interactivo) y espera confirmación.

Reglas de UX

1. Sé conciso. Sin IDs sin procesar, sin volcados JSON en el chat. Imprime la URL del medio para los activos generados, o el resumen de texto para Virality Predictor.
2. Sin jerga interna. No narres "llamando a higgsfield cost", "sondeando trabajo".
3. Detecta el idioma del usuario desde el primer mensaje y responde en ese idioma. Los argumentos técnicos (--aspect_ratio 16:9) permanecen en inglés.
4. No hagas preguntas por lotes. Elige un modelo predeterminado sensato y pregunta solo una cosa a la vez si realmente falta.
5. No estimes el costo ni optimices para modelos más baratos a menos que el usuario lo pida. Prefiere primero la calidad predeterminada.
6. Pasa --wait a generate create para que el comando se bloquee hasta que termine e imprima la URL del resultado. Evita el patrón de dos pasos create → wait.

Guardrail de descubrimiento

Cuando busques una característica/modelo de Higgsfield, no te bases solo en la búsqueda semántica o en --help de la CLI. Primero ejecuta una lista de modelos sin filtrar, luego inspecciona los nombres de job_set_type probables. Si el usuario dice que un modelo existe pero la búsqueda no devuelve resultados, confía en esa señal y verifica con la lista completa de modelos antes de responder.

Virality Predictor se expone como:

• Nombre público: Virality Predictor
• job_set_type técnico: brain_activity
• Categoría/salida: informe de texto. Es análisis de video con entrada de video y salida de texto, no un modelo de generación de texto/chat.
• Entrada: video subido
• Propósito: análisis del gancho, atención, retención y viralidad de un video terminado

Si el usuario dice "analiza este video", "puntúa este anuncio", "evalúa el gancho" o similar, dirige a brain_activity aunque aparezca bajo modelos de texto/análisis. Clasifica por intención de la tarea y entrada requerida, no solo por categoría de salida.

Flujo de trabajo — generación genérica

1. Elige un modelo. Comienza con los valores predeterminados principales a menos que el resumen necesite claramente un especialista:

   • GPT Image 2 → modelo de imagen predeterminado para generación general de alta fidelidad, diseño gráfico, UI, banners, tipografía y texto en imágenes.
   • Seedance 2.0 → modelo de video predeterminado para movimiento serio, clips cinematográficos, trabajo de múltiples tomas, imagen-a-video y salida de calidad de producción de 4 a 15 segundos. 12s es válido.
   • Nano Banana 2/Pro → predeterminado para trabajo de personajes, dibujos animados, estilizados y con imágenes de referencia; usa Pro para resúmenes más difíciles.
   • Marketing Studio → predeterminado para anuncios, UGC, demostraciones de productos, unboxing, anuncios de TV, videos de presentador y flujos de trabajo de marca/producto.

   Imagen:

   • Visual de producto de marca (pin de Pinterest, estilo de vida, banner principal, paquete de anuncios, prueba virtual) → usa higgsfield-product-photoshoot en su lugar. NO este skill.
   • Concepto de producto generado / empaque / lata / botella con nombre de marca o texto de etiqueta → GPT Image 2.
   • Imagen publicitaria con avatar + producto (forma de Marketing Studio) → Marketing Studio Image (ver Marketing Studio abajo)
   • UGC estético / editorial de moda / personaje de estilo de vida → Soul 2.0
   • Fotograma fijo cinematográfico → Soul Cinema
   • Persona creativa muy carismática (solo texto, distintiva) → Soul Cast
   • Ubicaciones / entornos / escenas sin personas → Soul Location (el mejor de su clase)
   • Ilustraciones vectoriales O edición de rostro + intercambio de escena complejo → Seedream 4.5
   • Personaje Soul (id de referencia de higgsfield-soul-id) → Soul 2.0 para imágenes fijas, Soul Cinema para cinematográfico
   • Trabajo de personajes o estilo dibujos animados → Nano Banana 2; sube a Nano Banana Pro en casos difíciles
   • Iteración rápida y barata → Z Image
   • Predeterminado para todo lo demás → GPT Image 2. Diseño gráfico, UI, banners, tipografía y generación general de alta fidelidad.

   Video:

   • Todo video publicitario / comercial / de marca → Marketing Studio (ver Marketing Studio abajo)
   • Video serio multiuso predeterminado (múltiples tomas, identidad consistente, mucho movimiento, imagen-a-video, solicitudes de 4 a 15 s) → Seedance 2.0. SOTA. No degrades a Seedance 1.5 solo porque su enumeración de duración es más fácil de leer; valida Seedance 2.0 primero.
   • Escena de un solo plano sin dinámicas fuertes, más barato que Seedance 2.0 → Kling 3.0
   • Toma limpia y barata sin cortes, solo cuando el usuario pide salida más barata/de presupuesto → Seedance 1.5 Pro
   • Mayor fidelidad de grado cinematográfico → Cinema Studio Video 3.0
   • Barato con buena física, sin necesidad de audio → Minimax Hailuo
   • Lote rápido / volumen → Veo 3.1 Lite

   Análisis de video:

   • Calificar el gancho, potencial de viralidad, atención, retención o riesgo de distracción de un video terminado → Virality Predictor (brain_activity). Este es un modelo de análisis de video que devuelve una puntuación/informe de texto, no un activo multimedia generado.

   Para el --model real que pasar a higgsfield generate create, ejecuta higgsfield model list --json | jq para mapear nombres de visualización a IDs. Consulta references/model-catalog.md para la tabla completa.

2. Pasa las entradas multimedia directamente a las banderas. Las banderas multimedia aceptan una ruta de archivo local o un UUID. La CLI sube automáticamente las rutas y detecta automáticamente trabajo vs subida para UUIDs. No es necesario pre-subir. Cada modelo declara los roles aceptados (image, start_image, end_image, video, audio) — consulta references/media-inputs.md.

3. Valida rápidamente. Si no estás seguro de los parámetros, ejecuta higgsfield model get <jst> --json una vez y pasa solo lo necesario. Valida el modelo preferido antes de recurrir a uno más antiguo. Usa los valores predeterminados del esquema en caso contrario. El servidor devuelve adjustments para conversiones no fatales (por ejemplo, aspect_ratio=99:99 → el más cercano) y un error estructurado para valores de parámetros declarados no válidos.

4. Envía y espera en una sola acción. higgsfield generate create <jst> [--prompt "..."] [banderas multimedia] [banderas de parámetros] --wait. Se bloquea hasta el estado terminal e imprime el resultado en stdout. Ajustables: --wait-timeout 20m (predeterminado 10m), --wait-interval 5s (predeterminado 3s). Virality Predictor no necesita un prompt; pasa --video.

5. Entrega. Para medios generados, envía la URL más un resumen de una línea (modelo, duración si es video). Para Virality Predictor, entrega las puntuaciones, la interpretación comercial y el enlace al informe Open. No muestres .glb, .bin o detalles internos de tablas de regiones en la salida normal del chat.

Para inspeccionar o reejecutar más tarde, higgsfield generate list --json y higgsfield generate get <id> --json funcionan para la retrospectiva. higgsfield generate wait <id> sigue disponible si alguna vez necesitas reincorporarte a un trabajo iniciado sin --wait.

Banderas multimedia

Banderas	Propósito	Modelos que lo aceptan
--image <ruta-o-id>	imagen de referencia	la mayoría de los modelos de imagen, seedance_2_0, veo3, marketing_studio_video
--start-image <ruta-o-id>	primer fotograma para transiciones imagen-a-video	kling3_0, kling2_6, veo3_1, seedance_2_0, marketing_studio_video
--end-image <ruta-o-id>	último fotograma para transiciones	kling3_0, seedance_2_0, marketing_studio_video
--video <ruta-o-id>	video de referencia o analizado	seedance_2_0, brain_activity
--audio <ruta-o-id>	audio de referencia (sincronización labial, coincidencia de banda sonora)	seedance_2_0 (usa este, NO --generate-audio)

Cada bandera acepta una ruta de archivo local (subida automáticamente) o un UUID (id de subida de higgsfield upload create, o un id de trabajo anterior). Cada modelo declara su propio conjunto de roles a través de MEDIA_ROLES. Consulta references/media-inputs.md para la tabla completa.

Parámetros comunes

Las banderas se pasan al esquema del modelo. Usa higgsfield model get <jst> para descubrirlos.

higgsfield generate create gpt_image_2 --prompt "ciudad de neón al atardecer" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "concepto de personaje anime, pose expresiva" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "la cámara avanza" --start-image ./first.png --duration 12 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait
higgsfield generate create brain_activity --video ./ad.mp4 --wait

Para salida legible por máquina (pipeline encadenado, contexto de agente), añade --json. Con --wait --json obtienes el objeto final del trabajo en un array. Sin --wait, obtienes los IDs de los trabajos. Virality Predictor almacena el análisis sin procesar y los artefactos de renderizado en los parámetros del trabajo, pero la salida de texto predeterminada debe mantener las puntuaciones más el enlace al informe Open.

Prompt de stdin: echo "..." | higgsfield generate create z_image --wait.

Calidad de imagen Soul: para text2image_soul_v2 y soul_cinematic, pasa --quality 1.5k o --quality 2k. Estos son niveles orientados a la UI; el backend los asigna a 720p/1080p y dimensiones específicas del modelo según el --aspect_ratio seleccionado. soul_location no tiene selector de calidad; usa dimensiones fijas por relación de aspecto.

Marketing Studio

Generación de imágenes/videos con marca: avatares + productos + ganchos/configuraciones opcionales + modos de estilo publicitario. Usa los modelos marketing_studio_video y marketing_studio_image.

Conceptos

• Avatar — rostro del presentador. preset seleccionado (navega higgsfield marketing-studio avatars list) o custom (fotos subidas a través de higgsfield marketing-studio avatars create). Para modos UGC, un avatar es opcional si el resumen menciona claramente a una persona; el backend puede crear un Soul Character automáticamente. Pasa un avatar cuando el usuario quiera un presentador específico.
• Producto — artículo de marca con título + imágenes de referencia. Importado desde URL (higgsfield marketing-studio products fetch --url ...) o creado a partir de imágenes subidas (higgsfield marketing-studio products create).
• Webproduct — versión de App Store / página web. Se enruta automáticamente al obtener URLs de App Store.
• Gancho (Hook) — ángulo/gancho de anuncio de apertura reutilizable. Navega con higgsfield marketing-studio hooks list. El texto del gancho se antepone al prompt del usuario; no reemplaza --prompt.
• Configuración (Setting) — contexto de entorno/escena reutilizable. Navega con higgsfield marketing-studio settings list.
• Referencia de anuncio (Ad reference) — video de inspiración reutilizable que se puede vincular a un avatar y/o producto. Se crea a partir de un video subido (--video-input <upload_id>) o un trabajo de generación anterior (--job <job_id>). Navega con higgsfield marketing-studio ad-references list. Consulta references/marketing-ad-references.md.
• Kit de marca (Brand kit) — captura la identidad de una marca (nombre, logotipo, imágenes principales, colores, fuentes, tono) para reutilizarla en generaciones de imágenes. Se crea proporcionando una URL de sitio web (higgsfield marketing-studio brand-kits fetch --url https://… --wait). Consulta references/marketing-brand-kits.md.
• Formato de anuncio (Ad format) — preajustes que determinan la estructura visual de una imagen generada (headline, bullet-points, etc.). Solo lectura, navega con higgsfield marketing-studio ad-formats list. Entrada requerida para dtc-ads generate.

Comandos de descubrimiento

Usa estos comandos de lista exactos cuando el usuario pregunte qué existe ya:

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json
higgsfield marketing-studio ad-references list --json
higgsfield marketing-studio brand-kits list --json
higgsfield marketing-studio ad-formats list --json

--hook_id y --setting_id son soportados solo por marketing_studio_video; no los pases a marketing_studio_image.

Reglas de UX (adicionales)

• Una pregunta por fase. No preguntes producto+avatar+modo por adelantado.
• Dos enfoques de anuncio son mutuamente excluyentes. O el usuario da un video de referencia de anuncio (impulsado por referencia) o elige bloques de gancho/configuración (compuesto de bloques) — nunca ambos. Si el usuario tiene una referencia de anuncio seleccionada, no ofrezcas gancho/configuración; si se han elegido gancho/configuración, no ofrezcas adjuntar una referencia de anuncio.
• Fuente de referencia de anuncio. Las únicas entradas válidas son un archivo de video local (subido a través de higgsfield upload create ... --video) o un trabajo de video anterior. Si el usuario proporciona cualquier otra cosa, pide un archivo local.
• dtc-ads requiere formato de anuncio. Siempre pide al usuario que elija de ad-formats list. No hay valor predeterminado automático — tanto la CLI como el servidor rechazan llamadas sin --format-id.
• Entradas opcionales de dtc-ads. Sugiere avatares, productos y medios de referencia cuando el resumen lo requiera; solo adjunta lo que el usuario elija.

Flujo de trabajo — video de anuncio rápido

1. Obtén el producto.
   • Producto existente → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait (sondea hasta que la importación termine)
   • Imágenes locales → higgsfield upload create <foto>... luego higgsfield marketing-studio products create --title "..." --image <id>... Captura el id del producto. Al usar --hook_id, es muy recomendable pasar --product_ids; los ganchos están diseñados para pivotar hacia un producto y funcionan mal sin contexto de producto.
2. Elige el avatar si es necesario.
   • Predeterminado: higgsfield marketing-studio avatars list y elige un preset que coincida con la voz de la marca.
   • Personalizado: higgsfield marketing-studio avatars create --name "..." --image <upload_id>. Para modos UGC, puedes omitir --avatars cuando no se requiera un presentador específico y el resumen mencione a una persona; el backend puede sintetizar un Soul Character.
3. Opcionalmente elige elementos de configuración.
   • Gancho: higgsfield marketing-studio hooks list --json
   • Configuración: higgsfield marketing-studio settings list --json Pasa los IDs seleccionados como --hook_id <hook_id> y --setting_id <setting_id> solo para marketing_studio_video. No copies el prompt del gancho en --prompt a menos que el usuario quiera explícitamente reforzar la misma redacción.
4. Elige el modo si es necesario. El predeterminado es ugc; --mode no es obligatorio solo porque --hook_id esté presente. Otros modos actualmente...

[truncado para la traducción]

Flujo de trabajo: anuncio de video con referencia

Cuando el usuario proporcione un video de referencia de anuncio, salta los pasos de gancho/configuración:

1. Obtén el video de referencia (subido o id de trabajo).
2. Crea una referencia de anuncio: higgsfield marketing-studio ad-references create --video-input <upload_or_job_id>.
3. Continúa con el avatar y el producto como en el flujo rápido.
4. Genera: higgsfield generate create marketing_studio_video --ad-reference-id <id> [--avatars <id>] [--product-ids <id>] --wait.

Flujo de trabajo: dtc-ads (anuncio de imagen)

1. Obtén el producto (igual que arriba).
2. Recupera la lista de formatos de anuncio: higgsfield marketing-studio ad-formats list --json.
3. Pide al usuario que elija un formato (obligatorio).
4. (Opcional) adjunta avatar y kit de marca.
5. Genera: higgsfield dtc-ads generate --format-id <id> --product-id <id> [--avatar-id <id>] [--brand-kit-id <id>] --wait.

Parámetros comunes (adicionales)

Bandera	Ejemplo	Notas
--aspect_ratio	16:9, 9:16, 1:1, 4:3	Cada modelo tiene soporte variable; el servidor devuelve adjustments si se pasa uno no válido.
--duration	5, 10, 12, 15	Segundos; seedance_2_0 acepta 4–15; kling3_0 acepta 5–10.
--resolution	720p, 1080p, 2k, 4k	Mapa a dimensiones internas.
--style	realistic, anime, cinematic, 3d-model	Varía por modelo.
--soul-id	<uuid>	Referencia de identidad de personaje Soul; usa el id de higgsfield soul list.

Ejemplos completos

# Imagen general de alta calidad
higgsfield generate create gpt_image_2 --prompt "paisaje urbano cyberpunk, lluvia, neones" --aspect_ratio 16:9 --resolution 2k --wait

# Video imagen-a-video
higgsfield generate create seedance_2_0 --start-image ./foto.png --prompt "transición a un bosque mágico" --duration 10 --wait

# Anuncio con avatar y producto (Marketing Studio)
higgsfield marketing-studio avatars create --name "Alex" --image ./foto_rostro.jpg
higgsfield marketing-studio products create --title "Zapatos Runner Pro" --image ./zapatos.png
higgsfield generate create marketing_studio_video --avatars <avatar_id> --product-ids <product_id> --hook_id <hook_id> --wait

# Análisis de viralidad
higgsfield generate create brain_activity --video ./video_final.mp4 --wait

Solución de problemas comunes

Problema	Solución
Model not found	Ejecuta higgsfield model list --json para verificar la existencia y el nombre correcto del modelo.
Upload failed	Verifica que el archivo exista y tenga permisos de lectura. Usa una ruta absoluta si es necesario.
Timeout	Aumenta --wait-timeout (por ejemplo, --wait-timeout 30m).
Invalid parameter	Ejecuta higgsfield model get <jst> --json para ver los parámetros aceptados y sus tipos.
Session expired	Pide al usuario que ejecute higgsfield auth login.
No ad format provided	Para dtc-ads, siempre debes pasar --format-id desde la lista de formatos.

Referencias

• Catálogo de modelos
• Entradas multimedia
• Referencias de anuncios de Marketing
• Kits de marca de Marketing