Cómo usar ideogram-v3-character a través de la API de HiAPI: guía de curl + Python

Qué es ideogram-v3-character y cuándo usarlo

ideogram-v3-character es un modelo de generación de imágenes en HiAPI centrado en la consistencia de personaje. No trata cada generación como un prompt independiente, sino que te permite proporcionar imágenes de referencia del personaje para que las renderizaciones posteriores mantengan el mismo rostro, vestimenta y características de identidad generales.

Debes usarlo cuando quién y qué hace importan por igual:

• Storyboards y cómics: el mismo personaje aparece en varias viñetas.
• Variantes de recursos para juegos: generar distintas poses, expresiones o vestimentas para un personaje protagonista.
• Mascotas de marca: deben mantener una imagen consistente en muchos escenarios y fondos diferentes.
• Dirección de arte iterativa: refinar el personaje a lo largo de varias rondas de ajustes sin perder el parecido.

Si solo necesitas una ilustración puntual y no te importa que coincida con imágenes anteriores, un modelo genérico de texto a imagen es más sencillo. La estructura adicional que aportan las imágenes de referencia es precisamente la razón por la que vale la pena añadir campos de solicitud específicos para ideogram-v3-character.

El modelo, al igual que los demás, se expone a través del endpoint unificado de generación de imágenes de HiAPI, por lo que la estructura de la solicitud resultará familiar: envías un payload JSON, recibes una referencia de trabajo de una tarea asíncrona y haces polling hasta que el resultado esté listo. Este tutorial se centra en cómo completar correctamente este flujo.

Antes de enviar la solicitud: configuración y autenticación

Antes de la primera llamada, solo necesitas preparar unas pocas cosas.

1. Clave de API

Crea una clave de API en el panel de control de tu cuenta de HiAPI. Trátala como un secreto: autoriza cada una de tus solicitudes y se factura a tu cuenta.

2. Gestión de credenciales basada en variables de entorno

Nunca codifiques la clave directamente en los archivos fuente ni la confirmes en git. Usa variables de entorno en su lugar:

export HIAPI_API_KEY="your_api_key_here"

En Python, puedes leerla así:

import os
api_key = os.environ["HIAPI_API_KEY"]

Si usas un archivo .env en el desarrollo local, añádelo a .gitignore antes de hacer cualquier otra cosa.

3. URL de la imagen de referencia

Como la consistencia de personaje depende de la imagen de referencia, prepara una imagen que pueda pasarse mediante URL. Asegúrate de que esa URL sea de acceso público o accesible de otro modo por la API: los enlaces privados detrás de autenticación fallarán. Las imágenes cuadradas o verticales que muestren claramente el rostro del personaje funcionan mejor.

4. Forma de realizar la solicitud HTTP

Basta con curl en la línea de comandos o un entorno de Python con requests instalado. Los ejemplos siguientes asumen que dispones de uno de los dos.

Con estos cuatro elementos preparados, ya puedes enviar tu primera solicitud.

Análisis línea por línea de una solicitud curl funcional

A continuación se muestra una solicitud completa para enviar un trabajo de ideogram-v3-character a HiAPI. Sustituye los marcadores de posición por tus propios valores.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-character",
    "prompt": "Un simpático mecánico robot de pie en un taller iluminado por el sol, sosteniendo una llave inglesa, vista de tres cuartos",
    "reference_images": [
      "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1
  }'

Función de cada parte

• POST /v1/images/generations — el endpoint unificado de generación de imágenes de HiAPI. Todos los modelos usan la misma ruta.
• Authorization: Bearer $HIAPI_API_KEY — autentica la llamada. El shell expande la variable de entorno que configuraste antes.
• Content-Type: application/json — estás enviando un cuerpo JSON, por lo que debes declararlo.
• model — selecciona ideogram-v3-character. Sin él, la solicitud no sabe a qué modelo enrutar.
• prompt — descripción de la escena. Describe la pose, el entorno, la iluminación y el ambiente; deja la identidad del personaje a la imagen de referencia.
• reference_images — array de URLs de imágenes. Para un solo personaje, normalmente basta con una entrada.
• aspect_ratio — forma de salida. Coincide con el uso previsto (cuadrado, vertical, etc.).
• num_images — cuántas variantes generar por trabajo.

Un envío exitoso devuelve un cuerpo JSON con el identificador del trabajo. Anota ese valor: lo necesitarás en el paso de polling. La respuesta también puede incluir un campo de estado que indique que el trabajo está en cola o en proceso. Si el estado ya es terminal, el resultado puede venir incrustado directamente en la respuesta; de lo contrario, continúa con el polling.

La misma solicitud en Python

A continuación se muestra exactamente la misma llamada en Python. Lee la clave de la variable de entorno, envía la solicitud e imprime la referencia del trabajo.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "ideogram-v3-character",
    "prompt": "Un simpático mecánico robot de pie en un taller iluminado por el sol, sosteniendo una llave inglesa, vista de tres cuartos",
    "reference_images": [
        "https://your-bucket.example.com/character-ref.png"
    ],
    "aspect_ratio": "1:1",
    "num_images": 1,
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=60)
response.raise_for_status()

job = response.json()
print(json.dumps(job, indent=2))

job_id = job.get("id") or job.get("job_id")
print("Job id:", job_id)

Notas sobre la versión de Python

• timeout=60 evita que el script se quede colgado indefinidamente con una red deficiente.
• raise_for_status() convierte las respuestas no 2xx en excepciones, para que notes de inmediato los problemas de autenticación y validación.
• Extracción del ID del trabajo — HiAPI devuelve el identificador del trabajo en el cuerpo de la respuesta. Según la estructura de la respuesta, puede estar en id o en job_id; el ejemplo comprueba ambos, pero deberías inspeccionar primero una respuesta real y luego codificar el nombre de campo correcto para mayor claridad.

El payload es deliberadamente idéntico al del ejemplo de curl. Copiar el cuerpo JSON de un lado a otro es una buena comprobación de cordura al depurar: si uno funciona y el otro no, el problema está en la capa de transporte, no en el modelo.

Gestión de imágenes de referencia para la consistencia de personaje

Las imágenes de referencia son precisamente lo que distingue a ideogram-v3-character de los modelos genéricos de texto a imagen. Si las gestionas bien, habrás resuelto más de la mitad del trabajo.

Cómo se proporcionan las imágenes de referencia

El campo reference_images es un array de URLs. Cada URL debe apuntar a una imagen que la API pueda recuperar directamente. Si almacenas contenidos subidos por usuarios, sírvelos desde un bucket o CDN que permita solicitudes GET no autenticadas, o genera una URL firmada que siga siendo válida durante la ejecución del trabajo.

Técnicas para imágenes de referencia que realmente mantienen la consistencia

• Un solo personaje por imagen de referencia. Las fotos de grupo dificultan determinar qué rostro conservar.
• Rostro claro y bien iluminado. Evita sombras intensas, ángulos extremos y oclusiones.
• Pose neutra o característica. La vista frontal o de tres cuartos conserva mejor los rasgos de identidad.
• Si quieres conservar la vestimenta, la ropa en la referencia debe ser consistente: el modelo reproducirá lo que ve.
• La resolución importa, pero no te excedas. Una imagen de tamaño razonable y rostro nítido supera a una enorme y borrosa.

Mantener al personaje reconocible en varias generaciones

Cuando generes una segunda escena para el mismo personaje, reutiliza la misma imagen de referencia, no la salida generada anteriormente. Encadenar imágenes generadas puede acumular derivas sutiles. Si necesitas una nueva referencia —por ejemplo, con otra vestimenta—, genera una vez, revísala y luego reutiliza ese archivo como nueva referencia para los trabajos posteriores.

Verificar la consistencia

Genera dos o tres variantes del mismo personaje en distintas poses y compáralas en paralelo. Si el rostro o la vestimenta se desvían, normalmente la causa es una imagen de referencia débil o ambigua. Antes de modificar el prompt, refuerza la imagen de referencia.

Trabajos asíncronos: enviar, hacer polling y obtener resultados

La generación de imágenes lleva tiempo, por lo que HiAPI la gestiona de forma asíncrona. El patrón es siempre el mismo: enviar, capturar el ID del trabajo, hacer polling hasta que el trabajo alcance un estado terminal y luego leer la URL de salida.

Ciclo de vida del trabajo

1. Enviado — envías la solicitud del ejemplo anterior.
2. En cola — el trabajo ha sido aceptado y espera capacidad.
3. En proceso — el modelo está renderizando.
4. Completado o fallido — estado terminal; el resultado (o error) está disponible.

Polling en Python

Tras capturar job_id, haz polling al endpoint del trabajo:

import time
import requests

def wait_for_job(job_id, api_key, interval=2, max_attempts=60):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("completed", "succeeded"):
            return data
        if status in ("failed", "error", "canceled"):
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Obtener el resultado

Cuando el trabajo se completa, el cuerpo de la respuesta contiene la salida: normalmente un array de URLs de imágenes o una única URL, además de metadatos. Descarga la imagen desde esa URL cuanto antes; algunas URLs tienen límite de tiempo. Si necesitas almacenamiento a largo plazo, copia el archivo a tu propio bucket inmediatamente después de que el trabajo tenga éxito.

Buenas prácticas de polling

• Retroceso. Un intervalo de dos segundos está bien para trabajos cortos; si haces polling de muchos trabajos, aumenta el intervalo o usa jitter.
• Limita el número de intentos. La protección max_attempts evita bucles infinitos y proporciona al código una ruta de fallo explícita.
• No hagas polling más rápido de lo necesario. Cada polling es una solicitud; saturar el endpoint no hará que el renderizado termine antes.

Errores comunes y cómo diagnosticarlos

Cuando algo falla, la vía más rápida suele ser aislar si el problema está en tu solicitud, en la imagen de referencia o en el trabajo en sí.

Fallos de autenticación

401 indica que la clave falta, tiene un formato incorrecto o ha sido revocada. Comprueba que la variable de entorno esté realmente configurada en el shell o proceso que ejecuta la solicitud. Trampa habitual: configurar la variable en un terminal y ejecutar el script en otro.

Errores de validación

400 casi siempre apunta al payload. Verifica:

• Que el campo model sea exactamente ideogram-v3-character.
• Que reference_images sea un array, no una cadena.
• Que cada URL del array sea de acceso público.
• Que aspect_ratio use un valor admitido.

Si no estás seguro, envía un payload mínimo —solo model, prompt y reference_images— y luego vuelve a añadir los campos uno a uno.

Trabajos que nunca terminan

Si el polling supera el límite de intentos, no te limites a reintentar a ciegas. Comprueba si la respuesta de estado del trabajo incluye algún mensaje. Las causas habituales son una URL de referencia inaccesible o una cola sobrecargada. Vuelve a enviar una vez; si vuelve a atascarse, simplifica el prompt y la imagen de referencia.

Imagen de referencia ignorada silenciosamente

El trabajo tiene éxito, pero el personaje no coincide. Normalmente es un problema de la imagen de referencia, no del código: la URL puede devolver una página de error, un PDF o una imagen de marcador de posición. Recupera tú mismo esa URL en el navegador para confirmar que devuelve la imagen esperada y con el tipo de contenido correcto.

Límites de tasa

429 indica que envías solicitudes demasiado rápido. Usa retroceso exponencial; si generas en lote, escalona los envíos en lugar de lanzarlos todos a la vez.

Lista de comprobación rápida

• ¿Está la clave configurada en el entorno correcto?
• ¿Es accesible la URL de referencia sin autenticación?
• ¿Están bien escritos los nombres de los campos del payload?
• ¿El polling tiene límite y retroceso?
• ¿Se descarga la salida antes de que expire su URL?

Si revisas esta lista punto por punto en orden, la mayoría de los fallos se resuelven rápidamente. Una vez que la primera ejecución de extremo a extremo funcione, consérvala como ejemplo validado y compara con ella cualquier nueva solicitud. A medida que escales a muchos personajes y escenas, este hábito por sí solo te ahorrará tiempo.