Tutorial
Cómo usar gpt-image-2.6-sunburst/image-to-image a través de la API de HiAPI: práctica con curl y Python
Enviar imágenes de referencia, consultar tareas asíncronas y depurar la solicitud de principio a fin
En esta página
Cuándo encaja gpt-image-2.6-sunburst/image-to-image
La generación de texto a imagen te da lo que el modelo produce libremente a partir de un prompt. La generación de imagen a imagen parte de material que ya tienes: proporcionas al endpoint una imagen de referencia y una instrucción, y el modelo genera una imagen nueva derivada de esa referencia. En HiAPI, gpt-image-2.6-sunburst/image-to-image es el endpoint dedicado a este segundo modo.
Elige este endpoint cuando la imagen de origen forme parte de los requisitos: por ejemplo, para rediseñar el estilo de material existente, ajustar la iluminación o la composición, aplicar un tratamiento visual a fotos de producto o generar variantes controladas de un diseño. La imagen de referencia es el ancla: aporta el sujeto, la paleta y el diseño, y tu prompt describe la transformación en lugar de describir la escena desde cero. Si no tienes material de origen y solo quieres obtener una imagen a partir de una descripción, el endpoint de texto a imagen es más sencillo y ofrece al modelo más libertad.
Dos implicaciones prácticas determinan todo lo que sigue. Primero, la solicitud transporta una entrada prácticamente binaria (una referencia de imagen), lo que afecta a cómo construyes el cuerpo de la solicitud. Segundo, la generación de imágenes no es instantánea, por lo que este endpoint funciona como una tarea asíncrona en lugar de devolver la imagen de forma inline. Planifica los dos pasos de «enviar» y «obtener», en vez de una única llamada bloqueante.
Requisitos previos y configuración de la autenticación
Antes de enviar la primera solicitud necesitas tres cosas: una cuenta de HiAPI, una clave de API y una forma de referenciar la imagen de origen que acepte el endpoint. Crea la clave en la consola de HiAPI y trátala como una contraseña: autoriza cada llamada que se factura a tu cuenta.
Pasa la clave como token bearer en la cabecera Authorization. No la codifiques directamente en archivos fuente, notebooks ni en el historial de commits. Expórtala como variable de entorno para las pruebas en el shell y, en el código de la aplicación, léela desde el entorno (o desde un gestor de secretos):
export HIAPI_API_KEY="your_api_key_here"
Decide de antemano cómo vas a proporcionar la imagen de referencia. Normalmente puedes subir el material a una ubicación temporal y pasar una URL, o enviar la imagen como datos codificados en base64 dentro del cuerpo de la solicitud. Una URL hace la solicitud más pequeña y fácil de registrar; base64 evita el alojamiento adicional, pero infla el cuerpo de la solicitud. Elijas lo que elijas, mantén el archivo en un formato compatible con el endpoint y comprueba los límites de tamaño antes de enviarlo. Anota también la URL base de la API de HiAPI correspondiente a tu cuenta: cada ruta de este artículo debe llevarla como prefijo.
Enviar una imagen de referencia con curl
Empieza en el shell, así verás exactamente qué se envía. La llamada consiste en un POST al endpoint de imagen a imagen, con un cuerpo JSON que contiene la imagen de referencia y la instrucción.
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
Campo por campo: model selecciona el endpoint; image lleva la imagen de referencia (aquí una URL; si no alojas el archivo, una cadena de datos base64); prompt es la instrucción de edición y debe describir el cambio, no volver a describir el sujeto; n es el número de salidas que quieres. Haz que el prompt sea concreto y acotado: las instrucciones que contradicen la imagen de referencia tienden a producir resultados confusos.
Envía la solicitud e inspecciona el cuerpo de la respuesta. Con un endpoint asíncrono no recibirás la imagen terminada; recibirás un identificador de tarea o un objeto de estado. Guarda esa respuesta antes de continuar: es el identificador para todo lo que venga después. Una comprobación rápida con curl -i también muestra el código de estado HTTP, la forma más rápida de distinguir un problema de autenticación (4xx al enviar) de un problema de contenido.
Realizar la misma llamada con Python
Cuando la llamada en el shell funcione, trasládala a Python. La biblioteca estándar basta, pero requests hace los ejemplos más legibles:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
Las diferencias con curl son mecánicas: la clave viene de os.environ, el cuerpo es un dict serializado a JSON y raise_for_status() convierte un envío fallido en una excepción en lugar de en un error silencioso. La última línea importa: la mayor parte del sufrimiento al depurar proviene de tratar una respuesta 4xx como un éxito y luego consultar un ID de tarea que nunca existió.
Para entradas binarias, lee el archivo, codifícalo en base64 y coloca la cadena en image en lugar de una URL. El resto del cuerpo de la solicitud no cambia, así que puedes alternar entre ambos métodos sin modificar la lógica de la solicitud.
Gestionar el ciclo de vida de las tareas asíncronas
La generación de imágenes lleva tiempo, por lo que el endpoint sigue el patrón de «enviar y luego consultar». Entiende los tres estados y el resto es trabajo de registro.
1. Enviar y capturar la tarea
Tu POST devuelve un identificador de tarea. Extráelo de inmediato y guárdalo en algún sitio persistente: una fila de base de datos, un mensaje de cola, una línea de registro consultable. Si tu proceso se cae entre el envío y la consulta, ese identificador es la única forma de recuperar el trabajo que ya has pagado.
2. Consultar hasta que la tarea termine
Consulta el endpoint de estado con el ID de tarea a intervalos fijos. Empieza de forma conservadora (unos segundos entre comprobaciones) y aplica un retroceso progresivo para tareas largas, para no saturar la API. Detente en un estado terminal: éxito, fallo o tu propio tiempo de espera. Nunca consultes en un bucle apretado.
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. Obtener y almacenar el resultado
En caso de éxito, la respuesta apunta a la imagen generada. Si la URL es temporal, descárgala a tiempo y escríbela en tu propio almacenamiento con un nombre que controles, para que los consumidores posteriores nunca dependan de un enlace temporal. Registra el ID de tarea junto al material almacenado: es la ayuda de depuración más barata que tienes.
En producción, la consulta debe ejecutarla un worker en segundo plano, no el manejador de la solicitud. Una solicitud web que se bloquea durante toda la generación de la imagen es frágil y ocupa una conexión sin necesidad.
Errores comunes y cómo solucionarlos
Cuando una llamada falle, recorre esta lista de arriba abajo; el primer punto captura la mayoría de los problemas.
401 / 403 al enviar
Problema de autenticación. Comprueba que la clave esté en la cabecera Authorization, que use el esquema Bearer y que no se hayan colado espacios en blanco ni saltos de línea al copiar y pegar. Confirma que la variable de entorno esté realmente definida en el shell o en el proceso que ejecuta la solicitud.
400 / 422 en el cuerpo de la solicitud
Cuerpo mal formado o algún campo incorrecto. Causas habituales: errores de sintaxis JSON provocados por una cadena curl escrita a mano, un valor de image que no es ni una URL accesible ni base64 válido, falta de prompt o un formato de imagen no compatible. Valida el JSON en local y confirma que la imagen de referencia se carga realmente en el navegador.
404 en el modelo o la ruta
Ruta o nombre de modelo mal escritos. El identificador del modelo es una cadena exacta: gpt-image-2.6-sunburst/image-to-image es distinto de la variante de texto a imagen y distingue mayúsculas de minúsculas.
Tiempos de espera y consultas colgadas
Distingue una tarea lenta de una tarea rota. Define un timeout para cada llamada HTTP, fija tu propio plazo global y, cuando te rindas, registra el último estado de tarea observado. Si las tareas superan tu plazo con frecuencia, auméntalo en lugar de pasar a un bucle de reintentos apretado.
Salida vacía o inutilizable
La tarea tuvo éxito, pero la imagen no es la que querías. Normalmente es un problema de prompt: la instrucción es demasiado vaga o entra en conflicto con la imagen de referencia. Haz que la instrucción de edición sea más concreta sobre qué debe cambiar y qué debe permanecer igual.
Recomendaciones de producción para un pipeline de imagen a imagen
Una vez que el prototipo funciona, lo que queda es fiabilidad y previsibilidad.
- Reintenta solo los errores que se pueden reintentar. Usa retroceso exponencial para los fallos de envío causados por 5xx y errores de red; no reintentes a ciegas los 4xx, solo volverán a fallar. Gestiona tú mismo la idempotencia vinculando la tarea a tu propio ID de solicitud, para que un reintento no duplique el trabajo.
- Separa el envío de la consulta. Coloca el envío y la consulta en workers o fases distintas. Así la latencia de tu API es independiente del tiempo de generación y puedes escalar la consulta por separado.
- Controla tu propio almacenamiento. Descarga el resultado en tu propio bucket en cuanto la tarea termine. Trata la URL devuelta como un enlace temporal.
- Versiona los prompts. Los prompts son activos de producción. Guarda el prompt, la imagen de referencia y el ID de tarea junto a cada salida, para que meses después puedas reproducir o explicar un resultado.
- Vigila la latencia y el gasto. Las tareas de imagen se facturan por salida, así que limita la concurrencia por usuario y registra el uso por tarea. Supervisa la latencia p95 desde el envío hasta el almacenamiento del material: esa es la cifra que perciben realmente los usuarios.
Una vez fijados la forma de la solicitud y el ciclo de vida, lo que queda es ingeniería habitual. Puedes encontrar los detalles del modelo en la documentación de HiAPI y, desde allí, conectar el endpoint a tu pipeline.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio