imraninho366/higgsfield-generate

Higgsfield Generate

Envía trabajos a cualquier modelo Higgsfield. Envuelve la CLI higgsfield. Abarca generación genérica de imágenes/video y Marketing Studio (anuncios de marca, avatares, productos, hooks, ajustes).

Paso 0 — Inicio

Antes de cualquier otro comando, asegúrate de que la CLI esté instalada y autenticada:

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

   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, abre un navegador) y espera a que confirme antes de continuar.

Omite ambas comprobaciones si higgsfield account status ya imprime información de la cuenta.

Reglas de UX

1. Sé conciso. Sin IDs sin procesar, sin volcados JSON en el chat. Imprime la URL del resultado cuando esté listo.
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 preguntes todo de golpe. Elige un modelo predeterminado sensato y pregunta una cosa a la vez solo si realmente falta.
5. No hagas una estimación previa del costo. Simplemente envía el trabajo a menos que el usuario lo pregunte.
6. Pasa --wait a generate create para que el comando se bloquee hasta que termine e imprima la URL del resultado por sí mismo. Evita el patrón de dos pasos create → wait.

Flujo de trabajo — generación genérica

1. Elige un modelo. Valores predeterminados prácticos basados en el uso en producción:

   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 esta habilidad.
   • Imagen publicitaria de marca con avatar + producto (formato Marketing Studio) → Marketing Studio Imagen (ver Marketing Studio más abajo)
   • UGC estético / editorial de moda / personaje de estilo de vida → Soul 2.0
   • Fotograma 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 rostros + intercambio de escenas complejas → Seedream 4.5
   • Soul Character (id de referencia de higgsfield-soul-id) → Soul 2.0 para imágenes fijas, Soul Cinema para cinematográfico
   • Iteración rápida y económica → Z Image
   • Trabajo con personajes o estilo caricatura → Nano Banana 2; sube a Nano Banana Pro en casos difíciles
   • 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 más abajo)
   • Video serio multiusos predeterminado (multi-toma, identidad consistente, mucho movimiento) → Seedance 2.0. Estado del arte.
   • Escena de un solo plano sin dinámicas fuertes, más barato que Seedance 2.0 → Kling 3.0
   • Toma limpia y económica sin cortes → Seedance 1.5 Pro
   • Máxima fidelidad de calidad cinematográfica → Cinema Studio Video 3.0
   • Económico con buena física, sin necesidad de audio → Minimax Hailuo
   • Lote rápido / volumen → Veo 3.1 Lite

   Para el --model real que se debe pasar a higgsfield generate create, ejecuta higgsfield model list --json | jq para asignar los nombres mostrados a los IDs. Consulta references/model-catalog.md para la tabla completa.

2. Pasa las entradas multimedia directamente como banderas. Las banderas multimedia aceptan una ruta de archivo local o un UUID. La CLI sube automáticamente las rutas y detecta automáticamente si el UUID corresponde a un trabajo o una subida. No es necesario subir previamente. 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. Usa los valores predeterminados del esquema para el resto. El servidor devuelve adjustments para conversiones no fatales (p. ej., aspect_ratio=99:99 → la coincidencia más cercana) y un error estructurado para valores de parámetros declarados no válidos.

4. Envía y espera en un solo paso. higgsfield generate create <jst> --prompt "..." [banderas multimedia] [banderas de parámetros] --wait. Se bloquea hasta el estado terminal e imprime la URL del resultado en stdout. Ajustables: --wait-timeout 20m (predeterminado 10m), --wait-interval 5s (predeterminado 3s).

5. Entrega. Envía la URL más un resumen de una línea (modelo, duración si es video).

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

Banderas multimedia

Banderas	Uso	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	seedance_2_0
--audio <ruta-o-id>	audio de referencia (sincronización de labios, coincidencia de banda sonora)	seedance_2_0 (usa ESTO, NO --generate-audio)

Cada bandera acepta una ruta de archivo local (se sube 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 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 hace un travelling". --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

Para salida legible por máquina (pipelines en cadena, contexto de agente), añade --json. Con --wait --json obtienes el array final de objetos de trabajo. Sin --wait, obtienes los IDs de los trabajos.

Prompt desde 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 interfaz de usuario; 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/video de marca: avatares + productos + hooks/ajustes de configuración 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 briefing 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 una URL (higgsfield marketing-studio products fetch --url ...) o creado a partir de imágenes subidas (higgsfield marketing-studio products create).
• Webproduct — versión de la página web / App Store. Se enruta automáticamente al obtener URLs de App Store.
• Hook — ángulo de apertura / gancho publicitario reutilizable. Navega con higgsfield marketing-studio hooks list. El texto del hook se antepone al prompt del usuario; no reemplaza --prompt.
• Ajuste — contexto de entorno / escena reutilizable. Navega con higgsfield marketing-studio settings list.

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

--hook_id y --setting_id son compatibles solo con 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.

Flujo de trabajo — video publicitario 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 hooks 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 briefing mencione a una persona; el backend puede sintetizar un Soul Character.
3. Opcionalmente, elige elementos de configuración.
   • Hook: higgsfield marketing-studio hooks list --json
   • Ajuste: 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 hook 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 slugs actuales: ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. Consulta references/marketing-modes.md.
5. Genera (de una sola vez).

   PRODUCT_IDS_JSON=$(mktemp)
   AVATARS_JSON=$(mktemp)
   printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
   printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"
   
   higgsfield generate create marketing_studio_video \
     --prompt "..." \
     --avatars @"$AVATARS_JSON" \
     --product_ids @"$PRODUCT_IDS_JSON" \
     --mode ugc \
     --duration 15 \
     --resolution 720p \
     --aspect_ratio 9:16 \
     --wait
   

   Añade --hook_id <hook_id> y/o --setting_id <setting_id> cuando se haya seleccionado un hook/ajuste de configuración. product_ids y avatars son arrays JSON; pásalos a través de @/ruta/al/archivo.json. No pases un UUID simple a --product_ids. La resolución es 480p o 720p. La relación de aspecto es una de auto/21:9/16:9/4:3/1:1/3:4/9:16. Aquí se admite --generate-audio true (a diferencia de seedance_2_0). --wait se bloquea hasta que termina; aumenta --wait-timeout 30m para campañas publicitarias más largas.
6. Entrega. URL + resumen de una línea (modo, duración).

Acceso directo Click-to-Ad (basado en URL)

Cuando el usuario proporciona una URL de producto y quiere un video de marketing de una sola vez:

# 1. Activar la obtención (devuelve el id del producto e inicia el raspado en segundo plano)
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. Generar el video de marketing contra la misma URL — el backend reutiliza la entidad
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

El backend desduplica por URL, por lo que las ejecuciones repetidas reutilizan la entidad existente en lugar de volver a obtenerla.

Flujo de trabajo — imagen de marketing

Igual que el anterior, pero usa el modelo marketing_studio_image:

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

Errores

• Missing required params: prompt → el usuario no dio un prompt; pídelo.
• Invalid values: aspect_ratio=99:99 (allowed: ...) → enum incorrecto; elige entre los permitidos.
• Unknown params: foo → el esquema no acepta esa bandera; comprueba higgsfield model get <jst>. Si esto ocurre para hook_id o setting_id, el modelo/job_set_type seleccionado no admite elementos de configuración de Marketing Studio.
• Session expired → higgsfield auth login.

Consulta references/troubleshooting.md para más información.

Documentos de referencia

Carga bajo demanda:

• references/model-catalog.md — elegir el modelo adecuado para la tarea
• references/prompt-engineering.md — escribir prompts que funcionen
• references/media-inputs.md — flujos de referencia de imagen/video
• references/troubleshooting.md — errores comunes y soluciones
• references/marketing-avatars.md — avatares preset vs personalizados
• references/marketing-products.md — obtención por URL vs creación manual de productos
• references/marketing-setup-items.md — descubrimiento y uso de hooks/ajustes
• references/marketing-modes.md — todos los modos de Marketing Studio