Blog

Tutorial

Cómo llamar a fibo-edit-1.5 de imagen a imagen mediante la API de HiAPI: guía con curl y Python

Explicación práctica de solicitudes ejecutables para la edición de imágenes basada en instrucciones

Nov 17, 2026
Imagen de portada: sobre un fondo casi negro, una banda de puntos verde menta que va de dispersos a densos, con un grupo de puntos verde azulado oscuro en el borde derecho.
En esta página

Qué hace el endpoint de imagen a imagen de fibo-edit-1.5

fibo-edit-1.5/image-to-image es un endpoint de edición de imágenes guiado por instrucciones. No describe una escena desde cero, sino que recibe una imagen de referencia y una instrucción en lenguaje natural, y devuelve una nueva imagen con esa edición aplicada mientras el resto de la composición permanece intacta.

Este planteamiento influye directamente en cómo diseñas la solicitud. La imagen de referencia aporta el contexto visual —el sujeto, el encuadre, la iluminación, el estilo— y la instrucción aporta el cambio. Una buena instrucción especifica qué hay que cambiar y guarda silencio sobre lo que debe permanecer igual. «Sustituye el cielo por un atardecer nublado, mantén el edificio y el primer plano sin cambios» comunica mucho más que «haz que se vea mejor».

Una llamada exitosa produce un recurso de imagen editado. Según cómo se invoque el endpoint, la respuesta devuelve la salida generada de una forma que puedes guardar u obtener; consulta la referencia del endpoint para conocer la estructura exacta de la respuesta y los parámetros admitidos. Trata esa referencia como la única fuente autoritativa de nombres de campos, formatos de imagen aceptables y límites de tamaño, ya que estos detalles pueden evolucionar con independencia de este documento.

Los usos típicos incluyen el retoque de fotos de producto, la sustitución de fondos, los ajustes de estilo y las ediciones locales en las que regenerar la imagen completa perdería fidelidad. Si tu tarea consiste solo en generar a partir de texto y no en editar, este endpoint no es la herramienta adecuada; utiliza en su lugar un modelo de texto a imagen.

Una expectativa que conviene fijar desde el principio: la edición es esencialmente iterativa. Rara vez tu primera instrucción acierta a la perfección, así que estructura tu flujo de trabajo en torno a iteraciones de bajo coste: cambia una sola variable cada vez, mantén la imagen de referencia igual y compara las salidas antes de pasar al siguiente paso.

Qué compone una solicitud funcional

Antes de escribir código, ten claro qué entradas necesita una solicitud. Cada llamada a fibo-edit-1.5/image-to-image combina cuatro tipos de información.

Autenticación

Todas las solicitudes pasan por la interfaz unificada de HiAPI y llevan tu clave de API en la cabecera Authorization. Guarda la clave en una variable de entorno en lugar de en el código fuente y no la confirmes nunca en un repositorio.

Imagen de referencia

Debes proporcionar la imagen de origen sobre la que actúa la edición. Hay dos formas habituales: una URL pública que el servicio pueda recuperar, o datos codificados en base64 incrustados en el cuerpo JSON. Las URL facilitan la iteración; base64 evita depender de un alojamiento externo. Consulta la referencia del endpoint para saber qué formas se aceptan y qué restricciones de tamaño o resolución existen.

Instrucción de edición

Es una cadena en lenguaje natural que describe el cambio. Redáctala en modo imperativo, indica la región o el elemento que hay que modificar y aclara qué debe conservarse. Evita acumular varias ediciones no relacionadas en una misma instrucción: sepáralas en varias llamadas para poder determinar cuál de ellas provocó un mal resultado.

Control de salida

Parámetros opcionales, como el tamaño, el formato de salida o el número de imágenes candidatas. En la primera llamada deja los valores predeterminados y ajústalos después de forma deliberada. Cada parámetro que estableces es una variable más que habrá que descartar cuando algo falle.

Por tanto, un cuerpo de solicitud mínimo tiene dos campos sustanciales —la imagen y la instrucción— dentro de un objeto JSON, con tus preferencias de salida adjuntas de forma opcional. Si puedes responder «qué imagen, qué cambio y en qué formato quiero recibirla», tienes todo lo necesario para escribir la llamada.

Realizar la llamada con curl

Empieza por curl: aísla la capa HTTP, de modo que, si algo falla, sabrás que el problema está en la solicitud y no en el código de la aplicación.

Primero exporta tu clave:

 export HIAPI_API_KEY="your-api-key"

Después envía el cuerpo JSON con la URL de la imagen de referencia y la instrucción:

curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "Sustituye el cielo apagado por un suave degradado de atardecer; mantén el edificio y el primer plano sin cambios."
  }'

Algunos consejos prácticos:

  • Confirma la URL base y la ruta con la referencia del endpoint; no las copies de memoria.
  • Usa -sS para que curl se mantenga silencioso cuando todo va bien, pero siga mostrando los errores de transferencia.
  • Si no quieres depender de un alojamiento externo, codifica el archivo en base64, sustituye el valor de image por la cadena codificada y respeta el nombre de campo indicado en la referencia.
  • Durante la fase de exploración, pasa la salida por jq . para que la respuesta sea más legible.

Para confirmar la respuesta, busca la carga útil o la URL de la imagen devuelta y ábrela. Si el cuerpo de la respuesta contiene un objeto de error, anota sus campos type y message: te indicarán si el problema está en la imagen, en la instrucción o en la estructura de la solicitud. Guarda una respuesta correcta sin procesar en un archivo; te servirá como fixture de prueba al escribir el cliente en Python y como evidencia si el comportamiento cambia en el futuro.

Realizar la misma solicitud con Python

La versión en Python debe coincidir exactamente con la llamada de curl —misma ruta, mismas cabeceras, mismo cuerpo—, de modo que cualquier diferencia sea un error en tu código y no una diferencia en lo que estás solicitando.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"

payload = {
    "image": "https://example.com/input.jpg",
    "prompt": (
        "Sustituye el cielo apagado por un suave degradado de atardecer; "
        "mantén el edificio y el primer plano sin cambios."
    ),
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)

Enviar un archivo local

Si editas un archivo del disco, codifícalo y envía la cadena en lugar de una URL:

import base64

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "image": encoded,
    "prompt": "Cambia el fondo por un gris neutro limpio; mantén el producto nítido.",
}

Antes de depender de este método, verifica en la referencia del endpoint el nombre exacto del campo y la codificación esperada.

Almacenar la salida

Escribe la imagen devuelta en disco para poder comparar los resultados de las iteraciones en paralelo y registrar qué instrucción produjo qué resultado. Una pequeña función auxiliar que guarde la salida con un nombre derivado del hash de la instrucción hará que las comparaciones posteriores sean triviales.

Asegúrate de establecer un timeout explícito. La edición de imágenes tarda más que una simple llamada de texto, y una solicitud sin límite de tiempo dejará el proceso de trabajo colgado indefinidamente si la red se detiene.

Manejar errores y reintentar de forma segura

Los fallos se agrupan en unas pocas categorías, y cada una requiere una respuesta distinta.

Errores de cliente

La solicitud en sí es incorrecta: JSON mal formado, falta el campo de imagen, formato de imagen no admitido, una instrucción que el modelo no puede ejecutar o un problema de autenticación. Reintentar estos errores tal cual solo desperdicia tiempo y cuota: volverán a fallar exactamente igual. Corrige la solicitud. Cuando aparezca uno de estos errores, registra el cuerpo completo de la solicitud (con la parte de imagen truncada) y el mensaje de error, y luego corrige la entrada.

Límites de tasa

Estás enviando solicitudes más rápido de lo permitido. La respuesta correcta es retroceder y reintentar, no martillear el endpoint. Sigue las indicaciones de reintento que proporcione la respuesta; si no las hay, usa retroceso exponencial.

Errores del servidor y transitorios

Los tiempos de espera agotados, los reinicios de conexión y los fallos del sistema upstream merecen un reintento. Aquí es donde entra en juego la lógica de reintento idempotente.

Estrategia de reintento práctica

  • Reintenta solo en caso de tiempo de espera agotado, error de conexión y respuestas de límite de tasa o del servidor.
  • Usa retroceso exponencial con un límite superior; por ejemplo, empieza con un retardo corto, duplícalo en cada intento y detente tras un número fijo y pequeño de intentos.
  • Añade jitter al retardo para que los procesos paralelos no reintenten todos en el mismo instante.
  • No reintentes nunca las solicitudes rechazadas por problemas de esquema, formato o instrucción.
  • Registra cada intento junto con su número y su resultado, para que puedas ver si los fallos se concentran.
import random, time, requests

def edit_with_retry(payload, attempts=4):
    delay = 1.0
    for i in range(attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        except (requests.Timeout, requests.ConnectionError):
            pass
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()
        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 2, 30)
    raise RuntimeError("La edición sigue fallando después de los reintentos")

Considéralo un esqueleto: alinea los códigos de estado reintentables con lo que devuelve realmente el endpoint y centraliza la política en un solo lugar para que todos los invocadores la compartan.

Comprobaciones antes de pasar a producción

Antes de conectar el endpoint en producción, completa una breve lista de comprobación.

Validar el camino feliz por partida doble

Vuelve a ejecutar con las mismas entradas la llamada de curl guardada y el cliente de Python, y confirma que producen resultados equivalentes. Si divergen, tu cuerpo de solicitud no es realmente el mismo.

Calibrar las instrucciones con entradas reales

Prueba tus instrucciones con imágenes representativas, no solo con una única muestra. La calidad de la edición depende en gran medida de la especificidad de la instrucción y de hasta qué punto la imagen de referencia admite ese cambio. Conserva un pequeño conjunto de pares instrucción-salida como suite de pruebas de regresión; cuando ajustes la redacción, podrás ver qué mejoró y qué empeoró.

Revisar límites y formatos

Confirma en la referencia del endpoint los formatos de imagen aceptables, el tamaño máximo y cualquier límite de tamaño de la solicitud. Valida en local antes de enviar: rechazar una imagen defectuosa en el cliente es más rápido y más barato que un viaje de ida y vuelta.

Verificar claves y registros

Asegúrate de que la clave de API proviene de una variable de entorno, de que los registros de solicitudes truncan la carga útil de la imagen y de que ninguna clave aparece en los informes de errores.

Confirmar el comportamiento ante fallos

Fuerza un tiempo de espera agotado y un cuerpo de solicitud mal formado en el entorno de preproducción, y comprueba que tu política de reintentos actúa correctamente y que los fallos permanentes se exponen al invocador en lugar de desaparecer silenciosamente.

Una vez que todo esto pase, la integración se volverá anodina de la mejor manera posible. Obtén la lista autoritativa de parámetros en la referencia del endpoint de imagen a imagen de fibo-edit-1.5 y luego construye a partir de una llamada de curl que funcione.

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