Cómo llamar a grok-imagine/image-to-image mediante la API de HiAPI: guía con curl y Python

Qué ofrece grok-imagine/image-to-image a los desarrolladores

grok-imagine/image-to-image es un endpoint de transformación de imágenes: le proporcionas una imagen de referencia y un prompt, y devuelve una nueva imagen que sigue el prompt mientras mantiene una relación visual con la imagen de referencia. Piénsalo como una generación guiada, no como una generación desde cero. El id de modelo que llamas en HiAPI es precisamente grok-imagine/image-to-image, y el resto de la solicitud sirve para describir el cambio que deseas.

Elige este endpoint en lugar de una llamada de texto a imagen siempre que la salida deba conservar algo del material existente: una foto de producto cuyo fondo hay que cambiar, un boceto de personaje que hay que renderizar, una composición cuyo estilo hay que modificar. La generación texto a imagen sirve cuando no tienes una imagen de origen y solo cuentas con una descripción; image-to-image sirve cuando la imagen de origen en sí misma forma parte de la especificación.

Como HiAPI lo expone como una única interfaz unificada, tu trabajo de integración se limita a construir una estructura de solicitud y a manejar una estructura de respuesta. No necesitas incorporar un SDK distinto para cada familia de modelos ni volver a aprender la autenticación para cada endpoint.

Anatomía de una solicitud: modelo, imagen de referencia y prompt

Toda llamada válida consta conceptualmente de cuatro partes. Acertar con cada una antes de escribir código te ahorra la mayor parte de la depuración posterior.

Id del modelo

El campo model lleva la cadena grok-imagine/image-to-image. Trátala como una constante en tu cliente, no como un literal codificado disperso por todo el código base: si más adelante quieres probar otro modelo de HiAPI, querrás tener un único lugar donde cambiarlo.

Imagen de referencia

La imagen de referencia es el ancla. Cómo la proporciones depende del método de transporte que elijas: puede ser una URL que la API pueda recuperar, o datos base64 en línea, útil para imágenes generadas al vuelo o que no son accesibles públicamente. Prefiere las URL para material que ya alojas; prefiere los datos en línea para cargas de usuarios que aún no están persistidas en ningún lugar público. Sea cual sea el transporte, valida la imagen antes de enviarla: formato admitido, tamaño distinto de cero y dimensiones suficientemente significativas.

Prompt

El prompt describe la transformación, no la escena completa. Si la imagen de referencia ya contiene el sujeto, describe lo que debe cambiar —estilo, iluminación, fondo, material— y deja implícito lo que no cambia. Especificar en exceso lo que ya es visible en la imagen de referencia suele entrar en conflicto con el condicionamiento de la imagen en lugar de ayudar.

Gestión de la relación de aspecto

La parte restante es cómo se determina el tamaño de salida, tema de la siguiente sección. Separa estas cuatro partes en el código que construye la solicitud para poder validar y registrar cada una de forma independiente.

Uso de la opción auto aspect

La opción auto aspect permite que la API elija el tamaño de salida en lugar de que fijes tú un ancho y un alto explícitos. Cuando está activada, el servicio deduce una relación de aspecto adecuada a partir del contexto de la solicitud —sobre todo de la imagen de referencia—, de modo que la forma de la salida resulta más razonable respecto a la entrada en lugar de verse forzada a un encuadre predeterminado.

Esto importa más de lo que parece. Si fijas un tamaño cuya proporción no coincide con la de la imagen de referencia, obtendrás artefactos tipo buzón de correo, recortes incómodos del sujeto o composiciones que ignoran el encuadre de la imagen de origen. auto aspect evita este tipo de desajustes al hacer que la geometría siga a la entrada.

Cuándo mantener auto activado

• Las imágenes de referencia proceden de usuarios y tienen formas diversas.
• Estás prototipando y aún no sabes qué tamaño encaja con el caso de uso.
• La salida pasa a una canalización posterior que de todos modos recortará o escalará.

Cuándo fijar un tamaño explícito

• Tienes una ranura fija en una UI o un destino de impresión que requiere una geometría de salida exacta.
• Estás generando un lote de imágenes que deben verse visualmente consistentes en tamaño.

Una práctica útil: mantén auto aspect activado durante el desarrollo, revisa qué tamaños devuelve la API para entradas reales y luego decide si fijar el tamaño para producción. Registra los metadatos de la imagen devuelta junto con la solicitud para que esa decisión se base en pruebas y no en conjeturas.

La solicitud curl lista para usar

La siguiente solicitud está completa salvo por los marcadores de posición, indicados entre corchetes angulares. Sustitúyelos por tus propios valores y podrás ejecutarla directamente.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

Marcadores de posición que hay que sustituir

• $HIAPI_API_KEY: lee tu clave desde una variable de entorno, en lugar de pegarla en el comando. Si la variable no está definida, la solicitud fallará con un error de autenticación y la clave nunca acabará en el historial de tu shell.
• <describe the transformation you want>: una instrucción breve y concreta, por ejemplo un cambio de estilo o de fondo.
• <publicly reachable URL of your reference image>: una URL que el servicio pueda recuperar sin autenticación. Si tu material es privado, usa datos base64 en línea en su lugar.

Lectura de la respuesta

En la primera ejecución, pasa la salida por una herramienta de formateo JSON para ver con claridad la estructura de la respuesta. Fíjate en dos cosas: la carga útil de la imagen (que según el modo de respuesta puede ser una URL o datos codificados) y el identificador de la tarea cuando la llamada se procesa de forma asíncrona. Durante el desarrollo, guarda la respuesta original completa en los registros: cuando algo parezca ir mal, es la forma más rápida de responder a «qué se devolvió realmente».

La misma solicitud en Python

La versión en Python debe corresponderse campo por campo con la solicitud curl. El valor de mantener ambas alineadas es que un error reproducido en una versión puede confirmarse en la otra sin tener que adivinar la traducción.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Dónde debe ir el manejo de errores

Envuelve la llamada, no al llamador. response.raise_for_status() convierte las respuestas que no sean 2xx en excepciones, de modo que un único try/except alrededor de generate_from_reference cubre tanto los fallos de transporte como los rechazos de la API. Si quieres registrar de forma estructurada el motivo del fallo, inspecciona response.status_code y el cuerpo del error dentro de la función antes de lanzar la excepción.

Mantener limpio el cliente

Lee la clave de API una sola vez al arrancar, define un tiempo de espera explícito y devuelve el JSON ya analizado en lugar del objeto de respuesta sin procesar. El llamador no debería necesitar conocer los detalles de HTTP. En las pruebas, apunta API_URL a un servidor simulado para poder validar la lógica de construcción de la solicitud sin gastar llamadas reales de generación.

Respuestas síncronas y asíncronas

Algunas solicitudes de image-to-image terminan lo bastante rápido como para devolver el resultado en la misma respuesta HTTP. Otras se procesan como trabajos: la llamada inicial devuelve un identificador y la imagen está disponible más tarde. Tu cliente no debe suponer ninguna de las dos cosas.

Cómo distinguir ambas

Inspecciona el cuerpo de la respuesta tras cada llamada. Si contiene directamente la carga útil de la imagen, estás en la ruta síncrona: extráela y devuélvela. Si contiene un identificador de trabajo o de tarea, estás en la ruta asíncrona y debes sondear hasta que el trabajo alcance un estado terminal.

Diseñar la estructura para ambas

Una pequeña función de despacho mantiene ambas rutas fuera de la lógica de negocio:

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Reglas de sondeo que evitan problemas

• Usa retroceso exponencial con un límite, no un bucle ajustado.
• Define un tiempo máximo total de espera y falla limpiamente cuando se supere.
• Trata cada estado no terminal como «sigue esperando»; solo hay dos estados finales: éxito y fallo.
• Registra el job id en cada sondeo para poder rastrear un trabajo atascado solo con los registros.

El planteamiento de despacho implica que el código que llama a resolve_result nunca necesita cambiar al alternar entre comportamiento síncrono y asíncrono.

Depuración de códigos de error habituales

La mayoría de las llamadas fallidas a este endpoint se agrupan en unas pocas categorías. Revisa la siguiente lista en orden: va del motivo más común al menos común.

Fallos de autenticación

Si la respuesta indica un problema de autenticación, la clave falta, tiene un formato incorrecto o no se envió. Comprueba que la variable de entorno está realmente definida en el proceso que realiza la llamada y que la cabecera es exactamente Authorization: Bearer <key>. Que la clave funcione en tu shell pero no en el servicio suele significar que el entorno del servicio es distinto del de tu shell.

Errores de validación de la imagen de referencia

Un rechazo relacionado con la imagen suele significar una de cuatro cosas: la URL no se puede recuperar públicamente, el formato no está admitido, la carga útil es demasiado grande o la imagen es demasiado pequeña o está dañada. Prueba la URL en un navegador sin credenciales: si no carga ahí, la API tampoco podrá recuperarla. Para base64 en línea, confirma que la codificación es base64 puro y que no lleva prefijo data-URL (salvo que el parámetro lo espere).

Errores de prompt y de parámetros

Un prompt vacío o demasiado largo, o un valor de parámetro desconocido, producen una respuesta de validación. Registra la carga útil exacta que enviaste junto con el error: una buena parte de los fallos son nombres de campo mal escritos, no problemas de valor.

Límites de tasa

Una respuesta de límite de tasa significa retroceder, no reintentar de inmediato. Sigue las indicaciones de reintento de las cabeceras de la respuesta, añade fluctuación aleatoria (jitter) y limita el número de reintentos. Reintentar sin retroceso convierte un límite temporal en uno persistente.

Errores del lado del servidor

Las respuestas 5xx son del lado del servicio. Reintenta un número limitado de veces con retroceso; si persisten, captura el id de solicitud y la marca de tiempo de la respuesta y reduce la concurrencia mientras investigas.

Lista de verificación de producción antes del lanzamiento

Una solicitud que funciona es el principio, no el final. Antes de que este endpoint maneje tráfico real, confirma cada uno de los siguientes puntos.

Validar la entrada en la frontera

Antes de que la solicitud salga de tu servicio, comprueba el formato y el tamaño de la imagen de referencia, la longitud del prompt y los valores de los parámetros. Rechazar una entrada incorrecta localmente es más rápido y más barato que un viaje de ida y vuelta, y produce mensajes de error más claros para el usuario.

Reintentar solo las solicitudes que sea seguro reintentar

Reintenta con retroceso exponencial y jitter los fallos de transporte, los límites de tasa y las respuestas 5xx. No reintentes los errores de validación ni de autenticación: fallarán de la misma manera y solo añadirán carga.

Registrar lo suficiente para reconstruir un fallo

Registra el id del modelo, una forma hasheada o truncada del prompt, el identificador de la imagen de referencia (no la carga útil completa), el estado de la respuesta, el job id (si existe) y el id de solicitud. Este conjunto suele bastar para responder a «qué ocurrió» sin almacenar contenido sensible.

Mantener las claves fuera del código

Lee la clave de API desde el entorno o un gestor de secretos, nunca desde un literal en el código fuente. Rota las claves periódicamente y revócalas de inmediato si sospechas que se han filtrado.

Vigilar el comportamiento de costes

El coste de este endpoint lo determina la generación, así que las palancas clave son el volumen de solicitudes, los reintentos y la frecuencia de sondeo. Evita tormentas de reintentos, aplica retroceso al sondeo y, cuando la misma transformación se solicite repetidamente, almacena en caché los resultados por prompt e imagen de referencia. Consulta el panel de precios de HiAPI para conocer las tarifas actuales en lugar de codificar suposiciones.

Probar las rutas que no van bien

Escribe pruebas para URL de imagen no válidas, respuestas de límite de tasa y trabajos asíncronos que nunca terminan. Estos tres casos cubren los fallos con más probabilidad de llegar a producción sin ser detectados.

Con la construcción de solicitudes, el despacho de respuestas y el manejo de errores resueltos, grok-imagine/image-to-image pasará a ser una parte habitual de tu canalización en lugar de un caso especial.