Cómo usar gpt-image-2.5-sunburst/image-to-image a través de la API de HiAPI: curl y Python

Capacidades de imagen a imagen de este endpoint

El endpoint gpt-image-2.5-sunburst/image-to-image sigue una convención sencilla: envías una imagen de referencia junto con una instrucción de edición en lenguaje natural, y el modelo devuelve una nueva imagen que aplica esa instrucción mientras permanece anclada a la referencia. A diferencia de texto a imagen —que parte de cero y depende por completo de tu prompt—, imagen a imagen trata la referencia como contexto visual: la composición, el sujeto, el estilo y las claves de color se heredan, a menos que tu instrucción pida explícitamente cambiarlos.

Esto lo convierte en la elección correcta cuando ya tienes material de partida y buscas una transformación controlada, por ejemplo, cambiar el estilo de una foto de producto, modificar la iluminación o el fondo, ajustar la apariencia del sujeto o generar variantes de un concepto existente. Elige texto a imagen cuando no tengas material de origen y desees la máxima libertad creativa; elige imagen a imagen cuando la fidelidad a una imagen existente importe más que la novedad.

El modelo mental clave que debe recordar el desarrollador: la imagen de referencia es una restricción de entrada, y la instrucción de edición es el incremento. Una buena instrucción describe qué debe cambiar, no todo lo que debe existir. «Cambia el fondo por un degradado de estudio limpio y conserva el sujeto y su sombra» funciona mejor que una descripción completa de la escena, porque la referencia ya proporciona la escena. Tenga esto en cuenta al leer la estructura de la solicitud a continuación: el cuerpo de la solicitud es pequeño, pero la calidad de la instrucción determina la calidad de la salida.

Preparación previa y estructura de la solicitud

Antes de la primera llamada, confirme que tiene tres cosas listas:

• Clave de API, emitida por su cuenta de HiAPI. Guárdela en una variable de entorno, no en el código fuente.
• URL base, es decir, la URL base de la API de HiAPI; consúltela en su panel o en la documentación de referencia de la API.
• Ruta del endpoint: gpt-image-2.5-sunburst/image-to-image.

Cada solicitud es una petición POST que lleva un cuerpo JSON y la cabecera Authorization. Conceptualmente, el cuerpo contiene tres partes lógicas:

1. Selección del modelo: el identificador del modelo de este endpoint, para que la pasarela enrute correctamente la llamada.
2. Entrada: la imagen de referencia (URL alojada o cadena de datos base64) y el texto de la instrucción de edición.
3. Control de salida: cualquier parámetro opcional indicado en la documentación del endpoint, como el tamaño o la cantidad. Use únicamente los parámetros que aparezcan en la documentación de referencia oficial; no adivine nombres.

Una advertencia sobre la disciplina: dado que es un endpoint alojado, los campos que acepta actualmente los define la documentación de referencia de la API vigente, no lo que se infiera de otras API de imágenes. En caso de duda, envíe primero el cuerpo válido mínimo (model, image, prompt), confirme que devuelve una respuesta 200 y luego añada los campos opcionales uno a uno. Así cada fallo se puede atribuir a un único cambio, en lugar de a un cuerpo ensamblado de golpe.

Enviar la imagen de referencia y la instrucción de edición

La imagen de referencia tiene dos formas de envío admitidas; la elección depende principalmente de dónde residen los bytes de la imagen.

URL alojada

Si la imagen ya es accesible públicamente, pase directamente su URL. Así el cuerpo es pequeño, la serialización es rápida y es la opción más sencilla durante el desarrollo. La URL debe poder ser recuperada directamente por el servicio: no puede estar detrás de autenticación, no puede ser una cadena de redirecciones ni una página HTML que casualmente contenga una imagen.

Datos base64

Si la imagen es local o un recurso privado, codifíquela y envíela en línea. Base64 infla el cuerpo aproximadamente un tercio, por lo que con imágenes de origen grandes puede acercarse al límite de tamaño. Si se aproxima al máximo, reduzca la resolución antes de codificar.

Errores de formato y tamaño

• Use formatos convencionales (PNG, JPEG, WebP) y asegúrese de que la extensión del archivo coincida con los bytes reales.
• Las imágenes demasiado grandes son la causa más común de rechazo de la solicitud. Elija una imagen de origen de tamaño razonable; normalmente no hace falta material a resolución completa para impulsar una edición.
• Si construye la cadena base64 por su cuenta, añada el prefijo de data URI solo si el ejemplo de la documentación de referencia de la API lo incluye; de lo contrario, omítalo. Mezclar estas dos convenciones es una fuente frecuente del error «invalid image».

Redactar la instrucción de edición

La calidad de la salida depende de la instrucción. Sea concreto sobre qué cambiar y especifique explícitamente qué conservar. Indique el objetivo («la chaqueta»), la transformación («recuerir de azul marino oscuro») y la restricción («mantén la pose de la modelo y las sombras existentes»). Evite apilar varias ediciones no relacionadas en una sola instrucción: si necesita cambios independientes, divídalos en varias llamadas, así cada resultado también será más fácil de evaluar.

Una solicitud curl ejecutable

A continuación tiene una solicitud que se puede ejecutar completa en la terminal. Sustituya los marcadores de clave e imagen por sus propios valores.

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.5-sunburst/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": "Sustituye el fondo por un degradado de estudio neutro y suave; mantén el sujeto, su pose y las sombras existentes sin cambios."
  }'

Desglose elemento por elemento:

• -X POST: la operación crea una nueva imagen, por eso se usa POST.
• La URL se compone de la URL base y la ruta del endpoint; guardar la URL base en una variable de entorno facilita cambiar de entorno.
• Authorization: Bearer ...: su clave de API. Expórtela como HIAPI_API_KEY para que no aparezca en el historial del shell ni en los registros.
• Content-Type: application/json: el cuerpo es JSON; omitir esta cabecera es una causa frecuente de respuestas 4xx confusas.
• model: el identificador del endpoint. Manténgalo exactamente igual que en la documentación.
• image: la imagen de referencia, aquí una URL alojada. Para usar base64, sustitúyala por la cadena de datos o por una variable codificada localmente.
• prompt: la instrucción de edición. Limítese a describir el cambio y lo que debe conservarse.

Si desea probar con un archivo local sin codificarlo manualmente, la mayoría de los shells permiten construir el JSON con un pequeño script o con jq; lo importante es que el cuerpo final sea JSON válido con estos campos.

La misma solicitud en Python

La versión en Python mantiene el cuerpo de la solicitud exactamente igual, para poder comparar las respuestas en paralelo. Use requests:

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": (
        "Sustituye el fondo por un degradado de estudio neutro y suave; "
        "mantén el sujeto, su pose y las sombras existentes sin cambios."
    ),
}

response = requests.post(
    f"{base_url}/gpt-image-2.5-sunburst/image-to-image",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

Hay dos detalles que merecen atención. Primero, json=payload establece el tipo de contenido y serializa el cuerpo por usted, lo que elimina toda una clase de errores al ensamblar JSON a mano. Segundo, timeout=120 es intencional: la generación de imágenes no es instantánea, y un cliente que espera para siempre es peor que un cliente que falla limpiamente. Ajuste el tiempo de espera a su carga de trabajo, pero siempre defínalo.

Para usar un archivo local, lea sus bytes, codifíquelos en base64 y asigne el resultado a image. Con una URL alojada, deje la cadena tal cual. Cuando las llamadas de curl y Python devuelvan la misma estructura, habrá confirmado que ambas se comportan igual y podrá seguir construyendo sobre cualquiera de las dos.

Diagnosticar fallos comunes de solicitud

La mayoría de los fallos se agrupan en cuatro categorías. Revíselas en el orden siguiente, porque cada una puede disfrazarse de la siguiente.

Errores de autenticación

Un 401 o 403 casi siempre significa que la clave falta, tiene un formato incorrecto o ha caducado. Compruebe que la cabecera sea exactamente Authorization: Bearer <key>, confirme que no se hayan colado comillas o saltos de línea adicionales al copiar y pegar, y verifique que la variable de entorno esté realmente definida en el shell o proceso que ejecuta la solicitud. Una clave que funciona en curl pero no en Python suele indicar una variable no definida, no una clave rota.

Cuerpo de solicitud mal formado

Un 400 con información de validación normalmente significa que el JSON es inválido o faltan campos obligatorios. Imprima el cuerpo con formato antes de enviarlo, confirme que model coincide con el identificador del endpoint y que el nombre del campo de la instrucción de edición coincide con la documentación. Al escribir JSON a mano en curl, las comas finales y las comillas simples son los culpables clásicos; el json= de Python los evita.

Entrada de imagen inválida o demasiado grande

Si el servicio rechaza la imagen, verifique tres cosas: que la URL sea recuperable públicamente y devuelva una imagen (no una redirección ni una página de error), que el formato sea compatible y que el cuerpo no supere el límite de tamaño indicado en la documentación. Para entradas base64, confirme que la codificación esté limpia y que la convención del prefijo de data URI coincida con el ejemplo de referencia. En caso de duda, reduzca la resolución y vuelva a intentarlo; una imagen de origen más pequeña resuelve buena parte de estos errores.

Tiempos de espera y fallos transitorios

Una generación larga puede superar el tiempo de espera del cliente, mientras que las respuestas 429 o 5xx indican que se activó el límite de tasa o que hubo un problema transitorio del servidor. Distíngalos de los errores del cliente: no reintente un 400 tal cual, pero un 429 o un 503 son buenos candidatos para un reintento con retroceso. Registre el código de estado y el cuerpo de la respuesta en cada fallo; un registro de errores claro convierte el diagnóstico de conjeturas en una lista de comprobación.

De un script a un cliente reutilizable

Un script desechable demuestra que el endpoint funciona; un pequeño envoltorio lo hace funcionar de forma estable en una canalización. Envuelva la llamada en una función que se encargue de tres cosas: la solicitud, el tiempo de espera y una política de reintentos acotada.

import os
import time
import requests

class ImageEditClient:
    def __init__(self, base_url: str, api_key: str, timeout: int = 120):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.timeout = timeout

    def edit(self, image: str, prompt: str, retries: int = 3):
        url = f"{self.base_url}/gpt-image-2.5-sunburst/image-to-image"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        payload = {
            "model": "gpt-image-2.5-sunburst/image-to-image",
            "image": image,
            "prompt": prompt,
        }
        last_error = None
        for attempt in range(retries):
            try:
                resp = requests.post(
                    url, headers=headers, json=payload, timeout=self.timeout
                )
            except requests.Timeout as err:
                last_error = err
                time.sleep(2 ** attempt)
                continue
            if resp.status_code in (429, 500, 502, 503, 504):
                last_error = RuntimeError(f"transient {resp.status_code}: {resp.text}")
                time.sleep(2 ** attempt)
                continue
            if resp.status_code >= 400:
                raise RuntimeError(f"request failed {resp.status_code}: {resp.text}")
            return resp.json()
        raise RuntimeError(f"exhausted retries: {last_error}")

Las decisiones de diseño importan más que el código en sí. El reintento se aplica solo a tiempos de espera y códigos de estado transitorios, nunca a errores de cliente 4xx, porque reintentar un cuerpo mal formado solo desperdicia cuota. El retroceso exponencial evita que una canalización limitada por tasa golpee repetidamente el endpoint. Los errores de cliente se lanzan de inmediato con el cuerpo de la respuesta, para que quien llama vea exactamente qué objeta el servicio. Y centralizar el identificador del modelo en un solo lugar significa que cambiar en el futuro a otro endpoint de imágenes requerirá una sola línea, sin tener que buscar por todo el código.

Sobre esta base, añada registro estructurado en cada intento y realice comprobaciones de tamaño/forma antes de que los consumidores posteriores usen la respuesta. Cuando esté listo para explorar otros modelos de imágenes en la misma pasarela, el catálogo de modelos de HiAPI es el lugar ideal para comparar endpoints sin reescribir el cliente.