La API de Higgsfield: cómo generar imágenes y vídeos con IA desde tu propio código

Qué es en una frase

Es una sola API para más de cincuenta modelos de imagen y vídeo: Kling, Seedance, Soul y el resto del catálogo de Higgsfield, todos con la misma forma de autenticarse y la misma forma de pedir y recoger resultados. Cambias de modelo cambiando una ruta, no reescribiendo la integración.

Lo que necesitas antes de empezar

1. Una cuenta en open.higgsfield.ai, que es la consola de la API. Puedes darte de alta como persona o como empresa.
2. Saldo. No hay suscripción ni prueba gratis: añades un método de pago y recargas, con un mínimo de 5 dólares.
3. Una clave de API. Tiene dos partes, un ID y un secreto, y el secreto se muestra una sola vez. Guárdalo en tu gestor de contraseñas en ese mismo momento.

Cómo funciona: pedir, esperar, recoger

Generar un vídeo tarda, así que la API no te devuelve el resultado en la misma respuesta. Funciona como un pedido en una cafetería:

1. Pides. Envías un POST a la ruta del modelo con tu prompt. La API responde al instante con un request_id, que es tu número de pedido.
2. Preguntas. Consultas GET /requests/<request_id>/status cada pocos segundos para ver cómo va.
3. Recoges. Cuando el estado es completed, la respuesta trae la URL de la imagen o del vídeo.

Estos son los estados que te puedes encontrar:

Un detalle que conviene saber desde el principio: las URLs de los resultados duran al menos siete días, no para siempre. Si vas a usar esa imagen en una campaña, descárgala y guárdala en tu propio almacenamiento en cuanto esté lista.

Tu primera imagen con curl

Primero guarda tus credenciales como variables de entorno en la terminal:

export HF_API_KEY_ID="tu-id-de-clave"
export HF_API_KEY_SECRET="tu-secreto"

Después pide una imagen al modelo Soul 2. Fíjate en la cabecera: la palabra Key, un espacio, el ID, dos puntos y el secreto.

curl -X POST https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
  -H "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Retrato editorial con luz natural suave"}'

La respuesta trae el request_id. Con él consultas el estado:

curl https://api.higgsfield.ai/requests/TU_REQUEST_ID/status \
  -H "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"

Repite esa consulta hasta que diga completed y copia la URL de images.

Lo mismo en Python, en tres líneas

Si trabajas en Python, el SDK oficial hace la espera por ti. Se instala con pip install higgsfield-client y lee la clave de una sola variable, HF_KEY, con el formato id:secreto:

import higgsfield_client

resultado = higgsfield_client.subscribe(
    "higgsfield-ai/soul/v2/standard",
    arguments={"prompt": "Retrato editorial con luz natural suave"},
)
print(resultado["images"][0]["url"])

subscribe envía el pedido, espera a que termine y te devuelve el resultado. También hay un SDK oficial para Node.js y TypeScript, @higgsfield/client, que funciona igual.

Cuánto cuesta

Se paga en dólares y solo por lo que generas: las imágenes, por imagen, y los vídeos, por segundo de vídeo. Dos ejemplos de la tarifa oficial a septiembre de 2026:

• Soul 2 (imagen): 0,0032 dólares por imagen. Con un dólar salen más de trescientas.
• Kling 3.0 (vídeo): 0,112 dólares por segundo. Un vídeo de cinco segundos cuesta unos 56 céntimos.

Lo mejor de la tarifa: lo que falla no se cobra. Si una generación termina en failed o nsfw, te devuelven lo reservado.

Al crear tu primera clave puedes tener veinte pedidos en marcha a la vez. Si te pasas, la API responde con un error, así que en una automatización conviene limitar cuántos lanzas en paralelo.

Los tres errores que te vas a encontrar al empezar:

• 401: la clave falta o está mal escrita. Revisa la cabecera, sobre todo los dos puntos entre el ID y el secreto.
• 403: no tienes saldo suficiente. Recarga y vuelve a intentarlo.
• 400: algún parámetro no es válido o has llegado al límite de pedidos simultáneos.

Cómo empezar hoy

1. Crea tu cuenta en open.higgsfield.ai y recarga 5 dólares.
2. Genera una clave y guarda el ID y el secreto en tu gestor de contraseñas.
3. Lanza el curl de arriba con Soul 2 y consulta el estado hasta tener tu primera imagen.
4. Cuando funcione, cambia la ruta por la de otro modelo del catálogo de la consola, por ejemplo uno de vídeo, y repite.
5. Descarga cada resultado a tu propio almacenamiento: las URLs caducan a los siete días.

Todo lo de este artículo sale de la documentación oficial de la API. Los precios y los modelos cambian a menudo, así que revísalos en la consola antes de montar algo grande.