Tutorial
Cómo llamar a qwen-image-3.0-pro/image-to-image mediante la API de HiAPI: curl, Python y una solicitud que funciona
Un recorrido de integración que cubre el patrón de tareas asíncronas, los clientes curl y Python, y el tratamiento de errores
En esta página
Por qué la generación de imagen a imagen (image-to-image) es una tarea asíncrona
Cuando llamas a un modelo de generación de imagen a imagen, no estás pidiendo una finalización de cadena que se devuelva en streaming en unos cientos de milisegundos. El modelo necesita cargar tu imagen de origen, ejecutar el proceso completo de generación de difusión condicionado por ella y codificar la salida. Esto puede tardar desde unos pocos segundos hasta decenas de segundos, y la duración varía con la resolución y los ajustes. Mantener abierta una conexión HTTP durante toda esa ventana no conviene a nadie: los proxies expiran, los balanceadores de carga descartan sockets inactivos y tus propios hilos de trabajo quedan atados a una solicitud que quizá aún falle más tarde.
Por eso el endpoint adopta un modelo de «enviar primero, sondear después». Tu primera solicitud envía una tarea y devuelve de inmediato un identificador de tarea. La generación de la imagen ocurre detrás de ese identificador. Después lanzas solicitudes independientes y muy ligeras para comprobar el estado de la tarea hasta que informe de que ha terminado, momento en el que la respuesta incluye el resultado que pediste.
Esto tiene consecuencias prácticas que deberías incorporar a tu diseño desde el principio:
- Enviar no es completar. Que la llamada de envío tenga éxito solo significa que la plataforma aceptó tu tarea, nada más. En el código, distingue ambos estados.
- El ID de tarea es tu único identificador. Guárdalo de forma persistente. Si tu proceso se cae entre el envío y el sondeo, el ID de tarea es la base para recuperarte sin reenviar (y volver a pagar por) el mismo trabajo.
- Sondear es ligero, pero no gratis. Las comprobaciones de estado son ligeras, pero un bucle apretado sigue generando tráfico y puede activar límites de frecuencia. Deja espacio entre comprobaciones.
- Los fallos llegan de forma asíncrona. Una imagen dañada o parámetros rechazados pueden aparecer como errores a nivel de tarea, no como un error HTTP en el envío. Tu código de sondeo debe leer el estado de la tarea, no solo el código de estado.
Con este modelo en mente, la integración posterior es directa: una llamada crea el trabajo, un bucle lo espera y un tratamiento deliberado de las tres cosas que pueden salir mal.
Antes de escribir código: qué necesitas tener preparado
Antes de tocar la terminal, reúne las pocas cosas de las que depende cada llamada de esta guía.
Credenciales de HiAPI
Necesitas una clave de API de HiAPI. Trátala como un secreto: cárgala desde una variable de entorno en lugar de pegarla en un script que podrías llegar a confirmar. Los ejemplos siguientes la leen como HIAPI_API_KEY. La URL base de la API y el identificador exacto del modelo qwen-image-3.0-pro/image-to-image son las dos constantes a las que harás referencia en todo momento.
Una imagen de origen
La generación de imagen a imagen necesita una entrada. Prepara una y decide cómo proporcionarla:
- como una URL de acceso público, o
- como un recurso ya subido o una carga codificada, según la forma que acepte el endpoint.
Antes de escribir la llamada, consulta el esquema de solicitud del modelo para confirmar los nombres exactos de los campos y los formatos de imagen de origen aceptables. Proporcionar una imagen de origen que el endpoint no acepta es la causa más común de que se rechace una tarea, y descartarlo de antemano es mucho más fácil que depurarlo a partir de un mensaje de error.
Un cliente que pueda sondear
Como la llamada es asíncrona, la herramienta que uses para enviar solicitudes también debe poder emitir solicitudes de seguimiento repetidamente. curl sirve para una primera prueba de humo; cualquier uso más duradero debería ser un script. No hay ninguna URL de callback que configurar ni ningún webhook que alojar: el sondeo es el mecanismo, así que planifica un bucle.
Un lugar donde ver el resultado
Decide de antemano cómo se ve «terminado» para ti: una URL que puedas abrir en el navegador o los bytes que escribes en disco. Saberlo antes de empezar hace evidente de un vistazo cuándo la integración funciona de verdad.
Con estas cuatro cosas a mano, la primera solicitud es breve.
Enviar una solicitud funcional con curl
La forma más rápida de confirmar que tu clave, tu endpoint y el ciclo de vida de la tarea funcionan es una sesión de curl en dos pasos. Primero envía; luego sondea.
Paso 1: enviar la tarea
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
Elemento por elemento:
-X POST—— enviar es una operación de creación.- La cabecera
Authorizationlleva tu clave. Al exportar la variable de entorno en lugar de escribirla en línea, evitas que quede en el historial del shell. Content-Type: application/json—— el cuerpo es JSON.-d—— la carga JSON. El campoimageapunta a tu imagen de origen ypromptdescribe la transformación que se debe aplicar. Los nombres de los parámetros y las opciones aceptables provienen del esquema de solicitud del modelo; verifícalos allí en lugar de adivinarlos.
La respuesta de un envío correcto es un objeto de tarea. Incluirá un identificador —llámalo ID de tarea— y un campo de estado que debería indicar que la tarea está en cola o en ejecución. Anota el ID de tarea; todo lo que sigue depende de él.
Paso 2: sondear la tarea
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
En cada llamada, lee el campo de estado. Cuando informe de un estado pendiente o en ejecución, espera unos segundos antes de volver a comprobar. Cuando informe de éxito, la respuesta contiene la imagen generada, normalmente una URL que se puede recuperar o datos codificados. Cuando informe de fallo, la respuesta incluye una descripción del error que explica el motivo.
Todo el ciclo de vida es así: un envío y luego comprobaciones de estado hasta un estado terminal. Cualquier cosa que construyas después será solo una versión más cómoda de estos dos comandos, más la espera y el tratamiento de errores.
Implementar la misma llamada en Python
Repetir a mano estos dos pasos de curl cansa enseguida, y copiar y pegar el bucle de sondeo en cada script es justo la forma en que se propagan los errores sutiles. Encapsula el patrón de envío y sondeo en una función reutilizable.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
Hay varias decisiones deliberadas que merece la pena señalar:
- Separar el envío de la espera. Si el envío falla, lo sabes antes de que ocurra ningún sondeo. Si más adelante quieres enviar en un proceso y recoger en otro, la costura ya existe.
- Cada solicitud tiene
timeout. Una solicitud sin tiempo de espera puede quedarse colgada indefinidamente, que es justo el modo de fallo que una API asíncrona debería ayudarte a evitar. - El bucle de sondeo tiene tanto un intervalo como una fecha límite global. Sin fecha límite, una tarea atascada en estado de ejecución daría vueltas para siempre. Sin intervalo, machacarías el endpoint.
- Las cadenas de estado se comparan de forma explícita. Cualquier estado que no sea éxito ni fallo pasa a la siguiente iteración, que es el comportamiento predeterminado correcto para los estados intermedios.
Llámala como llamarías a cualquier función: generate(source_url, "make the background a dusk cityscape"). El objeto devuelto es la carga de la tarea en estado terminal; extrae de ahí la referencia a la imagen.
Gestionar errores y tareas fallidas
Los errores en un flujo de trabajo asíncrono se dividen en tres categorías, y cada una requiere una respuesta distinta.
Rechazo a nivel de solicitud
Son las respuestas de error HTTP habituales de la llamada de envío: credenciales incorrectas o ausentes, JSON mal formado, parámetros no admitidos, imagen de origen inaccesible. Llegan antes de que exista ninguna tarea.
La respuesta correcta casi siempre es detenerse y mostrar el mensaje. Reintentar una carga mal formada solo desperdicia cuota y tiempo. Registra textualmente el código de estado y el cuerpo de la respuesta; el mensaje de validación suele indicar el campo problemático. Hay dos casos que merece la pena tratar especialmente: los fallos de autenticación deben fallar rápido y de forma visible, porque implican un problema de configuración; las respuestas de límite de frecuencia se pueden reintentar tras un retroceso exponencial.
Fallo a nivel de tarea
Aquí el envío tuvo éxito, el ID de tarea existe, pero el trabajo falló. La respuesta de sondeo informa de un estado de fallo junto con un error.
Esta categoría cubre problemas del propio modelo: la imagen de origen se puede decodificar pero no es utilizable, el prompt fue rechazado, la generación alcanzó un límite interno. Como dependen específicamente de la entrada, reintentar a ciegas suele reproducir el mismo fallo. Decide caso por caso: un error interno transitorio puede merecer un reintento; una imagen de origen rechazada nunca lo merece. Registra el ID de tarea junto con el error para poder correlacionarlo con una solicitud de soporte.
Sondeo que nunca termina
El envío tuvo éxito, la tarea existe, el sondeo está en marcha, pero el estado terminal nunca llega. Esto no es un error devuelto por la plataforma; es una suposición de tu código que debe caducar.
Protégelo con una fecha límite, como se muestra en el ejemplo de Python. Cuando se dispare la fecha límite, deja de sondear. No devuelvas silenciosamente un resultado a medias; lanza o devuelve un resultado de tiempo de espera explícito para que quien llama decida. Conserva el ID de tarea: puede que la tarea aún termine después de tu fecha límite y quizá quieras recogerla más tarde sin volver a enviarla.
Regla práctica para estas tres categorías: trata el estado de la tarea como la única fuente de verdad. El código de estado HTTP te dice si se aceptó la solicitud; el estado y el campo de error de la tarea te dicen si el trabajo tuvo éxito. Lee ambos, y los fallos se vuelven diagnosticables en lugar de misteriosos.
Encapsularlo en código de producción
La función anterior es una integración que funciona, no un servicio terminado. Antes de que soporte tráfico real, refuerza cuatro cosas.
Tiempos de espera en todas partes
Establece tiempos de espera explícitos de conexión y lectura para cada llamada: el envío, el sondeo y cualquier obtención posterior de la imagen resultante. Luego establece una fecha límite global para todo el ciclo de vida de la tarea. El tiempo de espera de la capa HTTP protege una solicitud individual; la fecha límite de la tarea protege la operación completa.
Reintentos con criterio
Reintenta solo lo que sea seguro reintentar. Los límites de frecuencia y los errores de red transitorios durante el sondeo cumplen la condición. Una carga rechazada no la cumple. Para los fallos a nivel de tarea, reintentar significa enviar una tarea nueva, lo cual es una operación distinta y más costosa que reintentar una comprobación de estado; trátalo como una decisión deliberada, preferiblemente con un límite.
Registros que incluyan el ID de tarea
Registra el ID de tarea en el momento del envío y en cada transición de estado posterior, junto con la información temporal. El intervalo entre el envío y el primer estado terminal es la métrica que realmente querrás cuando las cosas parezcan lentas. Cuando un usuario informe de un mal resultado, el ID de tarea es la clave para convertir una anécdota en un registro trazable.
Mantener el sondeo fuera de la ruta de la solicitud
Si tu función se ejecuta dentro de un manejador web, un bucle de sondeo síncrono mantendrá la solicitud abierta durante todo el tiempo de generación, que es justo el problema que el diseño asíncrono pretende evitar. En su lugar, envía en el manejador, devuelve el ID de tarea a quien llama y realiza la espera en un proceso de trabajo en segundo plano, una cola o una tarea programada. Después, el cliente sondea tu servicio, no el modelo.
Construido en este orden, la integración pasa de «funciona en mi máquina» a algo con lo que puedes contar: envía, guarda el identificador de forma persistente, espera con límites y deja que el estado de la tarea —y no la esperanza— te diga cuándo parar.
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