Tutorial
Cómo llamar a fibo-2.0/image-to-image mediante la API de HiAPI: práctica con curl y Python
En esta página
El lugar de fibo-2.0/image-to-image en la canalización
Los modelos de texto a imagen parten de una indicación; los modelos de imagen a imagen parten de una imagen que ya tienes. Esta diferencia parece pequeña, pero determina la posición del modelo en la canalización: fibo-2.0/image-to-image ya no es el primer paso que produce material desde cero, sino el paso de edición que transforma imágenes existentes.
El flujo de trabajo típico es así: obtienes o generas una imagen base, la envías a fibo-2.0/image-to-image junto con instrucciones que describen los cambios deseados y, después, entregas el resultado devuelto a las etapas posteriores: revisión, composición, almacenamiento u otra llamada a un modelo. Como el modelo recibe a la vez la imagen de entrada y la indicación, puede repintar el estilo, ajustar o transformar las partes que describes mientras conserva la composición, la posición del sujeto y la estructura general.
Cuándo elegir imagen a imagen en lugar de texto a imagen
Elige imagen a imagen cuando la salida deba mantener una relación reconocible con una imagen existente: repintar el estilo de una foto conservando el sujeto, ajustar la iluminación o el tratamiento del color, generar variantes de material ya aprobado o limpiar una imagen base tosca antes de su uso final. Si no tienes una imagen de partida y solo cuentas con una descripción, elige texto a imagen.
Lo que esta interfaz exige de ti
Esta llamada es el envío de un trabajo: envías la imagen de entrada, la indicación y los parámetros que quieras controlar, y la API devuelve un trabajo rastreable. Conviene considerar esta interfaz como una etapa bien definida dentro de una cadena mayor, no como una aplicación de edición completa: preparar la imagen de entrada y gestionar el resultado es responsabilidad tuya.
Como la solicitud es esencialmente asíncrona, el diseño de la integración debe girar en torno a ello: enviar, guardar el identificador del trabajo, sondear hasta que el trabajo termine y luego obtener la referencia de salida. El resto de esta guía consiste precisamente en construir ese flujo.
Preparación antes de enviar la solicitud
Antes de la primera llamada hay que tener tres cosas listas: credenciales, una comprensión correcta de la forma de la interfaz y una imagen de entrada preparada.
Credenciales
Todas las solicitudes enviadas a la API de HiAPI se autentican con una clave de API. La clave debe guardarse en el servidor; nunca la incrustes en código de navegador ni la confirmes en un repositorio. La práctica más limpia es leerla desde una variable de entorno, de modo que el mismo código funcione tanto en local como en el entorno desplegado:
export HIAPI_API_KEY="your-api-key"
Si aún no tienes una clave, créala primero en la consola de tu cuenta de HiAPI y luego continúa.
Forma de la interfaz
Este modelo se identifica en la API de HiAPI como fibo-2.0/image-to-image. Todas las llamadas a modelos comparten la misma URL base y las mismas convenciones de solicitud, lo que significa que, una vez que tienes una llamada funcional, cambiar a otro modelo consiste principalmente en modificar el identificador del modelo y los campos de la carga útil.
Preparar la imagen de entrada
Una solicitud de imagen a imagen necesita una imagen real, no una URL que esperas que se interprete. Decide de antemano cómo la vas a proporcionar: como archivo local subido con la solicitud o como una referencia aceptada por la API; y confirma que el formato funciona antes de escribir el código de la aplicación. Los dos fallos más habituales en la primera solicitud son enviar una ruta que solo existe en tu portátil y enviar un archivo con un formato que la interfaz no acepta.
Lista de comprobación práctica antes de construir la llamada:
- La imagen es un archivo real que tu lenguaje puede leer.
- La indicación describe la edición deseada en lenguaje llano, no solo una acumulación de palabras clave.
- Tienes claro qué parámetros enviar y cuáles dejar por defecto.
- Tu clave de API está disponible en el entorno desde el que se lanza la solicitud.
Con esto listo, puedes pasar a la solicitud en sí.
Análisis línea a línea de una solicitud curl funcional
Empieza por curl. Elimina toda abstracción entre tú y la solicitud HTTP; si algo falla, puedes estar seguro de que el problema está en la solicitud y no en una biblioteca cliente.
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
A continuación se explica qué hace cada parte.
Línea de solicitud
-X POST establece el método. La URL es la dirección base de la API de HiAPI más la ruta de generación de imágenes. Conviene guardar la dirección base en una variable o valor de configuración para no codificarla en varios sitios, de modo que un cambio futuro solo requiera editar un lugar.
Cabeceras
Authorization: Bearer $HIAPI_API_KEY lleva tus credenciales; el shell expande la variable de entorno que exportaste antes, así que la clave no aparece literalmente en el historial de comandos. Content-Type: application/json indica a la API que interprete el cuerpo de la solicitud como JSON. Enviar un cuerpo JSON y omitir esta cabecera es una causa habitual de errores difíciles de entender.
Carga útil
model identifica fibo-2.0/image-to-image. prompt es tu instrucción: describe la edición, no la imagen de salida completa, porque la imagen de entrada ya aporta la estructura. image es la forma de imagen de entrada aceptada por la interfaz; si se incrusta directamente, es la codificación base64 del contenido del archivo. n controla el número de salidas solicitadas; mantener el valor por defecto es el punto de partida más seguro.
Si la imagen es grande, incrustarla directamente en el comando de shell se vuelve engorroso. Codíficala primero en un archivo y luego referéncialo, o pasa directamente al método con Python de la siguiente sección, donde leer el archivo y codificarlo requiere una sola línea.
Leer la respuesta
No supongas que la respuesta contiene los bytes de una imagen ya terminada. Ejecuta la llamada curl e inspecciona el JSON: lo que buscas es un identificador de trabajo o un campo de estado para determinar si la tarea ha terminado o sigue en ejecución. Captura la estructura antes de escribir cualquier código de análisis, porque la forma de la respuesta determina cómo vas a sondear.
Portar la solicitud a Python
Python facilita el mantenimiento de la solicitud y permite encapsularla en una función reutilizable en todo el código. A continuación se muestra un cliente ligero para la misma solicitud:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
Por qué se usa esta estructura
Separar encode_image y submit_image_edit hace que el manejo de archivos y el manejo HTTP sean independientes y más fáciles de probar por separado. Leer la clave del entorno al importar hace que falle de inmediato si falta, en lugar de producir un 401 varias capas después. Establecer un timeout explícito evita que una conexión estancada deje colgado indefinidamente un proceso de trabajo.
Gestionar el cuerpo de la respuesta
raise_for_status() convierte los fallos de la capa HTTP en excepciones que se pueden capturar y registrar junto con el cuerpo de la respuesta; esto es mucho más útil que analizar silenciosamente un objeto de error como si fuera un éxito. Una vez obtenido el JSON analizado, registra el identificador de trabajo que contenga y, durante el desarrollo, registra la respuesta completa para ver con claridad qué campos existen realmente. No escribas analizadores basados en suposiciones; escríbelos basados en la respuesta que realmente observes.
Mantener la reutilización
Dos pequeñas mejoras dan fruto rápidamente: colocar la URL base y el nombre del modelo en constantes para que otras llamadas a modelos compartan este cliente, y hacer que la función de envío devuelva una estructura tipada (una pequeña dataclass o un dict con claves conocidas) para que el código de sondeo tenga un contrato estable en el que apoyarse.
Gestionar el ciclo de vida asíncrono y el sondeo
Los trabajos de imagen no se completan al instante. La integración debe tratar el envío y la finalización como dos eventos independientes.
Paso 1: enviar y persistir
Después de enviar el trabajo, guarda el identificador del trabajo en un lugar persistente: una fila de base de datos, un mensaje de cola o, como mínimo, una línea de registro. Si el proceso falla entre el envío y la finalización, un trabajo no registrado es trabajo perdido. Vincula el identificador con la entidad de tu sistema que posee el resultado para poder conciliarlo más adelante.
Paso 2: sondeo con retroceso
Sondea la interfaz de estado del trabajo a intervalos razonables. Un bucle ajustado que bombardea repetidamente la interfaz de estado desperdicia recursos y es el error asíncrono más habitual:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Empezar con un intervalo corto y aumentarlo mantiene la capacidad de respuesta de las primeras comprobaciones y evita solicitudes de alta frecuencia durante mucho tiempo. Un plazo máximo estricto evita esperar indefinidamente por un trabajo que nunca termina.
Paso 3: tratar los fallos como resultados normales
Un trabajo completado no es necesariamente un trabajo exitoso. Comprueba el estado antes de leer la salida y ramifica explícitamente ante el fallo: registra los detalles del error devueltos por el trabajo, emite una señal de reintento al llamador y decide si el reintento debe reutilizar la misma entrada o regenerarla. Un trabajo cuyo cliente ya agotó el tiempo de espera puede seguir ejecutándose en el servidor, así que no lo reenvíes a ciegas sin comprobarlo.
Paso 4: obtener y almacenar el resultado
Una vez que el trabajo informe éxito, lee la referencia de salida que proporciona y descárgala oportunamente. Si quieres almacenar el resultado a largo plazo, cópialo en tu propio almacenamiento en lugar de depender de que la referencia siga siendo válida para siempre.
Errores habituales y cómo corregirlos
La mayoría de los fallos se pueden agrupar en unas pocas categorías predecibles. Repasa esta lista en orden.
Fallos de autenticación
Un 401 o 403 casi siempre significa una cabecera incorrecta o una clave ausente. Confirma que la cabecera sea exactamente Authorization: Bearer <key>, con un espacio después de Bearer; y confirma que la variable de entorno esté realmente establecida en el proceso que realiza la solicitud, no solo en tu shell interactivo. Pegar la clave con espacios finales o comillas de más explica una proporción considerable de estos problemas.
Carga útil mal formada
Un 400 o 422 suele significar que la API no puede interpretar el cuerpo de la solicitud. Comprueba tres cosas en orden: si Content-Type: application/json está presente, si el JSON realmente se puede analizar (una coma final lo rompe) y si los campos obligatorios existen con el nombre correcto. Si envías datos de imagen en base64, confirma que sea base64 válido y que el formato de archivo subyacente esté soportado; una cadena truncada o codificada dos veces produce errores de validación confusos.
Errores de sondeo
Si un trabajo parece no completarse nunca, confirma que estás sondeando con el identificador realmente devuelto por la respuesta de envío y que lees el campo de estado correcto. Un bucle ajustado que ignora el estado failed parecerá un bloqueo. Añade un tiempo de espera máximo estricto y registra los cambios de estado observados; ese registro suele revelar el problema de inmediato.
Trampas al analizar la respuesta
Si el código lanza una excepción al leer el resultado, no adivines la forma de la respuesta. Registra primero el cuerpo de la respuesta sin procesar. Los problemas habituales incluyen confundir una referencia con bytes, suponer que los campos que solo existen en caso de éxito están siempre presentes y analizar una respuesta exitosa con un analizador de ruta de fallo. Construye la lógica de extracción basándote en las respuestas que realmente hayas visto.
Hábito de triaje rápido
Cuando algo falla, aísla primero la capa: ejecuta el comando curl con la misma carga útil. Si curl tiene éxito y Python falla, el error está en el cliente; si ambos fallan, el error está en la solicitud. Esta sencilla prueba ahorra más tiempo que cualquier otro hábito de depuración.
Con una llamada funcional y un bucle de sondeo robusto, fibo-2.0/image-to-image se convierte en un paso de edición fiable: empieza por la página del modelo en HiAPI y adapta la solicitud anterior a tus propias imágenes.
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