Blog

Tutorial

Cómo llamar a gpt-image-2.6-flare/image-to-image mediante la API de HiAPI: curl y Python

Subida de imágenes de referencia, solicitudes síncronas y asíncronas, y depuración de una llamada funcional

Nov 10, 2026
Imagen de portada: planos de hormigón escalonados que se entrecruzan bajo la luz solar oblicua, con una base gris cálida sobre la que se aprecia una zona de sombra gris azulada profunda y finas juntas en color salvia.
En esta página

Qué hace este endpoint y cuándo usar image-to-image

Los modelos de texto a imagen son excelentes para crear escenas desde cero, pero muchas tareas de producción parten de una imagen ya existente. gpt-image-2.6-flare/image-to-image es precisamente el endpoint que HiAPI ofrece para este tipo de tareas: envías una imagen de referencia y un prompt, y el modelo devuelve una imagen transformada que sigue tus instrucciones y se mantiene firmemente anclada a la imagen de referencia.

Los casos de uso típicos incluyen:

  • Transferencia de estilo y repintado: convertir una foto de producto en una ilustración estilizada, o redibujar una fotografía en otro lenguaje visual.
  • Edición y retoque: ajustar la iluminación, el fondo o la composición de material existente sin volver a fotografiar.
  • Generación de variantes: generar múltiples variantes visuales de un diseño base para pruebas A/B o exploración creativa.
  • Adaptación de material: ajustar el tamaño o recomponer la imagen de referencia para distintos canales, conservando su sujeto principal.

Si tu tarea consiste en «describir algo y obtener una imagen», texto a imagen es la opción más sencilla. Solo deberías usar image-to-image cuando el resultado deba derivarse claramente de una imagen de entrada concreta: esa imagen de referencia es el sentido mismo de la llamada. En el resto del artículo construiremos una solicitud real de principio a fin: primero con curl para demostrar que funciona, y después en Python para que puedas integrarla en tu servicio.

Requisitos previos y estructura de la solicitud

Antes de llamar a este endpoint, asegúrate de tener lo siguiente listo:

  • Una cuenta de HiAPI y una API key. La key se envía como bearer token en la cabecera Authorization. No la incluyas en repositorios de código; cárgala desde una variable de entorno (por ejemplo, HIAPI_API_KEY).
  • El id del modelo. Usa exactamente gpt-image-2.6-flare/image-to-image: el id del modelo distingue entre mayúsculas y minúsculas, y la barra forma parte del identificador.
  • La ruta del endpoint. La generación de imágenes se encuentra en la ruta de generación de imágenes del host de la API de HiAPI. Consulta la página del modelo para obtener la URL base y la ruta actuales, en lugar de codificar de forma fija algún host que hayas visto en fragmentos de código antiguos.
  • Un archivo de imagen de referencia, en un formato común (PNG o JPEG son opciones seguras por defecto). Mantén un tamaño razonable; los archivos demasiado grandes ralentizan la subida y pueden activar límites de solicitud.

Una solicitud a gpt-image-2.6-flare/image-to-image consta de tres partes clave:

  1. Selector de modelo: indica a HiAPI a qué modelo enrutar la solicitud.
  2. Prompt: la instrucción de texto que describe la transformación deseada. No es opcional; el prompt es la clave para guiar la edición.
  3. Imagen de referencia: la imagen de entrada sobre la que el modelo debe trabajar. Cómo pasarla depende del método de solicitud (ver la siguiente sección).

Aparte de esto, solo deberías enviar los parámetros que el modelo documenta en su página de modelo de HiAPI. Si te descubres inventando el nombre de un campo porque «parece correcto», detente y consulta la documentación: los parámetros desconocidos son una causa habitual de errores 4xx confusos.

Cómo pasar la imagen de referencia

Conceptualmente, la imagen de referencia no es más que otro campo de entrada en el cuerpo de la solicitud, pero su volumen la hace especial. Hay dos formas prácticas de pasar los bytes a la API, y esta elección afecta mucho más a tu código cliente que a la propia API.

Método A: incrustada en el cuerpo de la solicitud

Las imágenes pequeñas pueden incrustarse directamente en la carga JSON, normalmente como una cadena codificada en base64. Lees el archivo, lo codificas y colocas la cadena en el campo image de la solicitud. Todo va en una sola solicitud, lo que es ideal para miniaturas, iconos y fixtures de prueba.

El coste: base64 infla la carga aproximadamente un tercio, los codificadores JSON pueden no manejar cadenas muy largas, y depurar cuerpos de solicitud de varios megabytes en los registros es muy tedioso. Incrustar es por comodidad, no para material de gran tamaño.

Método B: subir primero y referenciar mediante URL

Para cualquier cosa que no sea una imagen pequeña, sube primero el archivo a un almacenamiento que controles y después pasa su URL como referencia. El cuerpo de tu solicitud se mantiene pequeño, reintentar es barato, y la misma imagen puede reutilizarse en varias llamadas sin volver a subirla cada vez.

Al usar URLs, ten en cuenta varios puntos:

  • La URL debe ser accesible públicamente por la API: no puede estar detrás de autenticación, ni ser localhost, ni un enlace firmado con caducidad que falle a mitad de la solicitud.
  • Usa un tipo de contenido aceptado por el modelo; si la URL devuelve HTML en lugar de una imagen, la validación fallará.
  • Prefiere nombres de archivo estables para poder correlacionar los registros entre tu almacenamiento y las solicitudes a HiAPI.

Sea cual sea el método elegido, la imagen de referencia y el prompt se envían en la misma solicitud. La API no exige un protocolo separado de «subir primero y generar después»: la llamada al modelo es una única operación lógica.

Llamadas síncronas y asíncronas

La generación de imágenes lleva tiempo, y por eso muchas API de imágenes ofrecen tanto un modo síncrono como un modo de tareas asíncronas. Aquí también se aplica este compromiso.

Síncrono

Envías la solicitud y mantienes la conexión abierta hasta que se devuelve la imagen. Tu código es una línea recta: construir la solicitud, POST, leer la respuesta, terminar.

Usa llamadas síncronas cuando:

  • Estés creando un prototipo o depurando y quieras ver el resultado completo en un paso.
  • La solicitud se ejecute en un entorno en el que bloquearse un tiempo sea aceptable (herramientas CLI, workers en segundo plano).
  • Quieras el cliente más sencillo posible, sin lógica de sondeo.

La desventaja es que una generación larga implica mantener la conexión abierta mucho tiempo, y cualquier proxy o balanceador de carga entre tú y la API puede imponer sus propios tiempos de espera.

Asíncrono

Envías la solicitud como una tarea, recibes inmediatamente un identificador de tarea y después sondeas (o recibes una devolución de llamada) hasta que la tarea termina. Tu cliente necesita una pequeña máquina de estados: enviar, esperar, obtener el resultado, gestionar fallos.

Usa llamadas asíncronas cuando:

  • Estés sirviendo tráfico orientado al usuario y no puedas permitirte bloquear el hilo de la solicitud.
  • Estés generando muchas imágenes en lote y quieras distribuirlas en paralelo y recoger los resultados.
  • Tu infraestructura tenga tiempos de espera de solicitud cortos que no controlas.

Cómo elegir: si alguien espera el resultado dentro de una solicitud web, usa asíncrono. Si un script o worker espera sin conexión, lo síncrono es más sencillo y perfectamente válido. No lo compliques en exceso: empieza con síncrono y pasa a asíncrono cuando los tiempos de espera o los límites de concurrencia reales te obliguen a ello.

El resto del artículo usa el modo síncrono, porque hace visible cada paso, pero el cuerpo de la solicitud que construyes es idéntico en ambos modos: solo cambia la infraestructura que lo rodea.

Una solicitud curl funcional

Construyamos la llamada desde la terminal. Primero configura tu key:

export HIAPI_API_KEY="your-api-key-here"

Paso 1: preparar la imagen de referencia

Empieza con una imagen pequeña y verificada, para que si algo falla la causa no sea ambigua:

ls -lh reference.png
file reference.png

file debería informar PNG image data o JPEG image data. Si informa otra cosa, corrígelo antes de continuar.

Paso 2: enviar la solicitud

La solicitud es un POST al endpoint de generación de imágenes, con un cuerpo JSON que contiene el modelo, tu prompt y la imagen de referencia. Según el método de subida elegido, el campo image será una URL o una cadena base64.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png"
  }'

Sobre estos parámetros:

  • -sS oculta la barra de progreso pero sigue mostrando los errores; ideal para scripts.
  • Authorization: Bearer $HIAPI_API_KEY evita que la clave aparezca en el propio comando.
  • $HIAPI_BASE_URL se configura desde la página del modelo; no adivines el host.
  • Aquí el campo image usa el método de URL; para imágenes incrustadas, sustitúyelo por una cadena base64.

Paso 3: leer la respuesta

Añade -i para incluir las cabeceras de respuesta y -w '\nHTTP %{http_code}\n' para imprimir el código de estado. Una llamada correcta devuelve la imagen (o un enlace a ella, según el formato de respuesta) junto con metadatos. En caso de fallo obtendrás un código de estado 4xx o 5xx y un cuerpo de error JSON; antes de cambiar cualquier otra cosa, lee el campo message.

Paso 4: redirigir la salida a un archivo

Para obtener un archivo limpio, redirige stdout a un archivo y vuelve a comprobarlo con file. Si la respuesta es un JSON que contiene una URL, extrae esa URL y descárgala con un segundo curl. Antes de conectar esto a cualquier automatización, verifica siempre que los bytes descargados sean realmente una imagen.

La versión en Python de la misma solicitud

La base en curl se traduce directamente a Python. Este ejemplo solo usa la biblioteca estándar más requests:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(data)

Gestionar la respuesta

El formato de respuesta varía: puede contener la imagen directamente o incluir una URL. Escribe una pequeña función auxiliar que unifique ambos casos, para que el código posterior no tenga que preocuparse por cuál es:

def extract_image(data):
    if "url" in data:
        return requests.get(data["url"], timeout=60).content
    if "image" in data:
        import base64
        return base64.b64decode(data["image"])
    raise ValueError(f"Unexpected response shape: {list(data)}")

Gestionar errores

No dejes que raise_for_status() sea tu única vía de error. Envuelve la llamada y expón el mensaje de error de la API:

try:
    response = requests.post(url, headers=headers, json=payload, timeout=120)
    response.raise_for_status()
    image_bytes = extract_image(response.json())
except requests.HTTPError as e:
    print("HTTP", e.response.status_code, e.response.text)
    raise
except requests.Timeout:
    print("Request timed out; consider the async job route instead")
    raise

Variante asíncrona

Para el modo asíncrono, envía la tarea con la misma carga, lee el id de tarea de la respuesta y después sondea el endpoint de estado de la tarea con una breve pausa entre intentos. Pon un límite al número de sondeos y trata agotar el presupuesto como un fallo; nunca sondees indefinidamente dentro de un manejador de solicitudes.

Diagnosticar errores comunes

La mayoría de los fallos se agrupan en unas pocas categorías. Revisa esta lista en orden; cada paso aísla una variable.

Errores de autenticación (401 / 403)

  • ¿Está HIAPI_API_KEY realmente definida en el shell o el proceso? echo $HIAPI_API_KEY debería imprimirla.
  • ¿Es la cabecera exactamente Authorization: Bearer <key>, con A mayúscula, B mayúscula y un espacio?
  • ¿Se ha revocado o rotado la key? Vuelve a generarla y reintenta con una solicitud mínima.

Carga de imagen de referencia no válida

Este es el fallo más frecuente, y normalmente no es culpa del modelo:

  • URL inaccesible: abre la URL de la imagen en un navegador de otra red. Si devuelve 404 o redirige a una página de inicio de sesión, la API tampoco podrá acceder a ella.
  • Tipo de contenido incorrecto: las URLs que devuelven HTML o JSON se rechazan. Usa curl -I <url> para confirmar que la respuesta es Content-Type: image/....
  • Archivo corrupto o ilegible: ejecuta file reference.png localmente. Verifica que la cadena base64 decodificada coincida byte a byte con el archivo original.
  • Archivo demasiado grande: consulta los límites de tamaño documentados en la página del modelo; reduce el tamaño antes de reintentar.

Formato de parámetros incorrecto

  • Error tipográfico en el id del modelo: gpt-image-2.6-flare/image-to-image debe coincidir exactamente, incluida la barra.
  • Falta el prompt: la instrucción de texto es obligatoria y no puede omitirse.
  • Campos sobrantes: elimina cualquier parámetro que no encuentres en la documentación. Las claves desconocidas suelen provocar 4xx.
  • Sintaxis JSON: valida el cuerpo de la solicitud con jq . <<< "$BODY" antes de enviarlo.

Tiempos de espera agotados

Si la solicitud se interrumpe antes de que se devuelva la imagen, significa que la conexión se mantuvo abierta demasiado tiempo. Acorta el prompt, reduce la imagen de referencia, aumenta el tiempo de espera del cliente; si el problema persiste, cambia al modo de tareas asíncronas: las generaciones largas son justo el caso de uso de lo asíncrono.

Estrategia de depuración

Cambia solo una variable en cada intento. Empieza con una imagen de referencia muy pequeña y verificada y un único prompt para demostrar que la infraestructura funciona, y después introduce gradualmente las entradas reales. Registra el cuerpo completo de la respuesta en cada fallo; el campo message suele señalar directamente qué parte de la solicitud es incorrecta.

Integrar en tu pipeline

Una vez que la base funciona, unos cuantos hábitos mantienen gpt-image-2.6-flare/image-to-image fiable en producción.

Valida las entradas antes de la llamada. Comprueba que la imagen de referencia tiene un formato compatible y está dentro de los límites de tamaño y, si es una URL, que es accesible. Rechaza entradas incorrectas en tu propio límite, en lugar de pagar por un viaje de ida y vuelta fallido.

Valida las salidas después de la llamada. Confirma que la respuesta contiene bytes de imagen reales (comprueba los números mágicos), y no una página de error HTML colada. Una comprobación barata de las cabeceras ahorra mucha depuración confusa aguas abajo.

Reintenta con retroceso exponencial, pero solo para los errores correctos. Los 5xx transitorios y los tiempos de espera de red merecen un reintento con retroceso exponencial y jitter; los errores 4xx causados por parámetros incorrectos fallarán exactamente igual todas las veces, así que corrige la solicitud en lugar de reintentarla.

Prefiere lo asíncrono para el trabajo orientado al usuario. Si alguien espera en una página, envía una tarea y sondea desde el cliente; no mantengas abierta una solicitud web para una generación larga.

Mantén los ids de modelo en la configuración. Los ids de modelo cambian con el tiempo. Léelos desde un único punto de configuración, para que cambiar de modelo sea una sola línea en lugar de un buscar y reemplazar global.

Combínalo con otros modelos de HiAPI. Este endpoint encaja de forma natural con texto a imagen para componer flujos híbridos (generar primero una imagen base y después editarla); y, si tu pipeline lo necesita, con pasos de ampliación o eliminación de fondo. Como todo pasa por la misma interfaz y autenticación de HiAPI, añadir un paso es solo otra llamada con la misma key.

Empieza con la base en curl, pásala a Python y cambia a asíncrono cuando el tráfico lo requiera. La página del modelo ofrece los parámetros de solicitud y los límites actuales; consúltala antes de asumir un nombre de campo o un límite de tamaño.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API