Blog

Tutorial

Cómo usar Google Virtual Try-On a través de la API de HiAPI: guía con curl y Python

Nov 10, 2026
Prismas geométricos planos y abstractos divididos en planos de verde salvia y verde pino sobre un fondo verde profundo; portada de un tutorial para desarrolladores.
En esta página

Qué espera el modelo google-virtual-try-on

Antes de escribir cualquier código, conviene entender el contrato de entrada. El modelo google-virtual-try-on es una tarea de composición de dos imágenes: recibe una imagen de persona/modelo y una imagen de prenda, y genera una imagen de la persona vistiendo esa prenda.

Esto significa que tus pasos de preparación siempre tienen la misma forma:

  • Una imagen de persona con el sujeto claramente visible y un encuadre razonable; las tomas de cuerpo entero o de medio cuerpo funcionan mejor, porque el modelo necesita entender la geometría del cuerpo.
  • Una imagen de la prenda, preferiblemente sobre un fondo limpio o liso, que muestre la pieza que quieres transferir a la persona.

Amas entradas se proporcionan como URL de imagen, no como datos binarios sin procesar en el cuerpo de la solicitud. Esto mantiene la carga útil de la solicitud pequeña y permite que tu propia capa de almacenamiento (S3, GCS, CDN) siga siendo la fuente de verdad. Por lo tanto, tu trabajo consiste en asegurarte de que cada URL sea accesible públicamente antes de realizar la llamada, o que esté firmada con una validez suficientemente larga.

Hay algunas restricciones prácticas que conviene planificar con antelación:

  • La resolución y la relación de aspecto afectan la calidad de la salida. Las miniaturas diminutas o las entradas excesivamente recortadas suelen producir resultados deficientes.
  • Cada llamada procesa una sola prenda. Si tu página de producto tiene varios colores, realiza varias llamadas en lugar de intentar meter varias piezas en una sola solicitud.
  • El emparejamiento es responsabilidad tuya. El modelo no valida si la prenda «le queda bien» a la persona; simplemente compone lo que le proporcionas. Un buen emparejamiento (cuerpo entero con vestido, medio cuerpo con chaqueta) produce claramente mejores resultados.

Considera este paso como el contrato de activos: si puedes generar de forma fiable dos URL de calidad para cada tarea, el resto del trabajo de integración es una simple construcción de tuberías.

Configura tu solicitud a HiAPI

Todas las llamadas a modelos de HiAPI siguen la misma forma, así que una vez que tengas una funcionando, las demás solo requieren cambiar parámetros. Esto es lo que necesita google-virtual-try-on.

Endpoint y método

La solicitud se envía con POST al endpoint de llamada a modelos de HiAPI de google-virtual-try-on. Usas la misma URL base y el mismo conjunto de credenciales en todos los modelos, que es la razón principal para enrutar a través de HiAPI en lugar de integrar cada proveedor por separado.

Autenticación

Autentícate con tu clave de API de HiAPI en la cabecera Authorization, en el formato estándar de token bearer:

Authorization: Bearer $HIAPI_API_KEY

Mantén la clave en el lado del servidor. Nunca la distribuyas en un paquete de navegador o en una aplicación móvil; proxyar a través de tu propio backend es más seguro y además te da un lugar donde añadir limitación de tasa y registro.

Tipo de contenido

Envía el cuerpo de la solicitud como JSON:

Content-Type: application/json

Cuerpo de la solicitud

El cuerpo de la solicitud lleva tu identificador de modelo y las dos URL de imagen de la sección anterior —la imagen de la persona y la de la prenda—, además de cualquier parámetro opcional que exponga el modelo. Los nombres exactos de los parámetros son los que se documentan junto al modelo; cópialos literalmente en lugar de adivinarlos, porque un error tipográfico en el nombre de un campo suele manifestarse como un error de validación, no como un mensaje útil.

Guarda tu configuración

Coloca la URL base, el identificador de modelo y la clave en variables de entorno, para que el mismo script funcione en preproducción y producción sin modificaciones:

export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

Eso es toda la configuración. Sin SDK, sin integración por proveedor.

Una solicitud curl funcional

La forma más rápida de confirmar que la clave y la carga útil son correctas es una única llamada curl. Aquí está la anatomía de una solicitud a google-virtual-try-on:

curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-virtual-try-on",
    "input": {
      "model_image": "https://your-cdn.example.com/person-001.jpg",
      "garment_image": "https://your-cdn.example.com/jacket-front.jpg"
    }
  }'

Hay algunos puntos que conviene tener en cuenta:

  • Los dos campos de imagen están dentro del objeto input, lo que mantiene los parámetros específicos del modelo aislados por espacio de nombres y separados de los campos de enrutamiento.
  • Las URL deben ser accesibles desde el servidor, no desde tu portátil. Una dirección localhost o accesible solo por VPN fallará.
  • No hay paso de carga de archivos en esta llamada. Si tus activos aún no están en un CDN, súbelos primero y usa las URL generadas.

Ejecútala una vez y revisa el JSON sin procesar devuelto antes de construir nada encima. Canalizar la salida a través de un formateador facilita la lectura:

curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

Guardar el cuerpo de la solicitud en un archivo request.json también evita errores de comillas del shell cuando la carga útil crezca.

La misma solicitud en Python

Para cualquier escenario más allá de una prueba puntual, pasa a Python. El ejemplo siguiente usa solo la biblioteca estándar más requests, por lo que se puede colocar directamente en un script, una Lambda o un pequeño servicio sin necesidad de marcos adicionales.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")


def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
    payload = {
        "model": "google-virtual-try-on",
        "input": {
            "model_image": person_url,
            "garment_image": garment_url,
        },
    }
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/google-virtual-try-on",
        json=payload,
        headers=headers,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = try_on(
        "https://your-cdn.example.com/person-001.jpg",
        "https://your-cdn.example.com/jacket-front.jpg",
    )
    print(result)

Notas sobre la adaptación:

  • Establece un tiempo de espera explícito. La generación de imágenes no es instantánea; el tiempo de espera predeterminado de requests es demasiado agresivo para este tipo de llamadas. Elige un valor cómodamente superior a tu latencia p99.
  • Usa json=payload, no data=json.dumps(payload). Establece el tipo de contenido por ti y evita errores de doble codificación.
  • Devuelve el JSON analizado, no el objeto de respuesta, para que quien llame no dependa accidentalmente de detalles internos de HTTP. Si necesitas el código de estado para métricas, captúralo antes de devolver.
  • Separa el cliente del flujo de trabajo. En un servicio real, la función anterior pertenece a un módulo cliente ligero; la cola, el almacenamiento y los reintentos se sitúan en la capa superior.

Si ya usas httpx o un marco asíncrono, la conversión es mecánica: la carga útil y las cabeceras son idénticas.

Leer la respuesta

La respuesta es JSON. Trátala como un pequeño sobre que se centra en dos cosas: si la tarea tuvo éxito y dónde está la salida.

En términos generales, debes comprobar:

  1. Estado de transporte. Un 2xx indica que la solicitud fue aceptada y procesada. Un 4xx indica que tu solicitud tiene un error; un 5xx indica que algo falló en el servidor. Registra el código de estado en cada llamada: es la medida de observabilidad más barata que puedes añadir.
  2. Campos del cuerpo de respuesta. La carga útil lleva el resultado generado. El resultado de imagen se devuelve como una URL que apunta al activo generado. Los nombres exactos de los campos dependen del esquema de respuesta del modelo; analiza de forma defensiva en lugar de asumir una única cadena.
  3. Metadatos. Cualquier campo de uso o duración en la respuesta merece ser capturado. La facturación se mide en la plataforma, por lo que persistir metadatos por solicitud te permite conciliar más adelante tus propios registros con el panel de control.

Un análisis robusto es el siguiente:

data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
    raise RuntimeError(f"No image in response: {data}")

Cómo gestionar el resultado

La URL devuelta es el activo generado, no un activo permanente. No la pases directamente al frontend y te olvides. En su lugar:

  • Descarga y rehospeda. Obtén los bytes de inmediato y escríbelos en tu propio bucket con una clave direccionada por contenido. Esto desacopla tu producto de la política de retención del generador.
  • Registra la procedencia. Almacena las URL de entrada, el identificador de modelo y la marca de tiempo junto con la salida. Cuando un comerciante pregunte por qué una prueba virtual se ve así, necesitarás reproducir la tarea exacta.
  • Normaliza el formato. Redimensiona y convierte al formato estándar de la tienda una sola vez al ingerir, en lugar de procesarlo en cada vista de página.

Tratar la respuesta como un traspaso efímero —analizar, descargar, almacenar, descartar— es el patrón escalable.

Modos de fallo y estrategia de reintentos

No todos los fallos merecen un reintento. Reintentar a ciegas convierte un pequeño hipo del proveedor en una cola llena de tareas duplicadas y una factura sorprendente.

Clasifica antes de reintentar

No reintentes: corrige la solicitud:

  • Errores de validación del tipo 400: JSON mal formado, campos ausentes o con nombres incorrectos, cuerpo de solicitud que no se ajusta a la estructura esperada por el modelo.
  • 401/403: clave de API incorrecta o ausente, o clave sin permiso para acceder a ese modelo. Reintentar nunca ayudará.
  • 404: identificador de modelo o ruta de endpoint incorrectos.
  • URL de imagen inaccesibles. Si la URL de la persona o de la prenda devuelve 404 o expira al obtenerse, la generación no puede continuar. Valida las URL antes de enviar.

Reintenta con retroceso:

  • 429: te han limitado la tasa. Retrocede y respeta la señal.
  • 5xx: error transitorio del servicio o del proveedor.
  • Fallos a nivel de red: restablecimiento de conexión, tiempo de espera de lectura.

Reintentos acotados con jitter

Limita el número de intentos —tres es un límite habitual— y usa retroceso exponencial con jitter aleatorio, para que un grupo de workers no reintente de forma sincronizada:

import random, time

def with_retry(fn, attempts=3, base=1.0):
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise  # client error: do not retry
            if i == attempts - 1:
                raise
            time.sleep(base * (2 ** i) + random.uniform(0, 0.5))

Protecciones en producción

  • Idempotencia a nivel de tarea. Hashea el par de URL de entrada como clave de tarea. Si la misma clave ya está en ejecución o completada, devuelve el resultado almacenado en lugar de reenviar.
  • Cola de mensajes muertos. Cuando se agoten los reintentos, aparca la tarea con su contexto completo en lugar de descartarla silenciosamente.
  • Disyuntor. Si la tasa de errores supera un umbral, deja de enviar durante un periodo de enfriamiento en lugar de seguir golpeando un servicio en apuros.
  • Alertas por forma, no solo por cantidad. Un pico de 4xx tras un despliegue suele significar que alguien renombró un campo.

Valida las entradas cuanto antes

La mayoría de los «fallos del modelo» son en realidad entradas deficientes. Haz una verificación previa barata: envía un HEAD a cada URL, comprueba el tipo de contenido y las dimensiones aproximadas, y rechaza los activos claramente inutilizables antes de gastar una llamada facturada. Este único hábito elimina la mayor parte de tu tráfico de reintentos.

Integrarlo en una tubería real

Una llamada curl exitosa es solo una demostración. Una función de producto fiable requiere un poco más de estructura a su alrededor.

Estructura el flujo en etapas

Una descomposición viable:

  1. Ingesta. El comerciante o el usuario interno envía la imagen de la persona y la de la prenda. Almacena ambas en tu almacenamiento de objetos y genera URL estables y firmadas.
  2. Validación. Comprueba accesibilidad, formato y dimensiones. Rechaza pronto con mensajes claros.
  3. Envío. Llama a google-virtual-try-on mediante el módulo cliente. Registra en la base de datos la clave de tarea, el identificador de modelo y las URL de entrada.
  4. Materialización. Tras el éxito, descarga la imagen generada, conviértela a tu formato estándar y escríbela en tu CDN con una clave determinista.
  5. Publicación. Actualiza el registro de la tarea para que apunte a tu activo alojado y haz que la tienda lea solo desde tu propio almacenamiento.

Cada etapa se puede reintentar de forma independiente, que es precisamente la razón por la que todo el sistema es depurable. Si el paso 4 falla, no necesitas volver a ejecutar la generación.

Mantén el cliente ligero

Coloca la llamada HTTP en un módulo pequeño y sitúa la política (reintentos, concurrencia, tiempos de espera, registro) a su alrededor. Cuando HiAPI añada parámetros al modelo, o quieras hacer pruebas A/B de distintas rutas de generación de imágenes, solo tendrás que cambiar un archivo.

Hábitos operativos que vale la pena adoptar

  • Asíncrono por defecto. La generación tarda segundos, a veces más. Envía desde un worker, no desde el manejador de solicitudes en el que el usuario está esperando.
  • Cachea de forma agresiva. El mismo par de persona y prenda nunca debería generarse dos veces. Direcciona las salidas por contenido y compruébalo antes de enviar.
  • Presupuesta con visibilidad. Dado que el uso se mide en la plataforma, registra metadatos por solicitud y concílialos periódicamente con tu panel de HiAPI. Descubre bucles de reintentos descontrolados en horas, no a fin de mes.
  • Versiona las indicaciones y los parámetros. Almacena el objeto de parámetros con cada tarea para poder reproducir resultados tras un cambio.
  • Falla de forma visible para el usuario. Un spinner que nunca desaparece es peor que un honesto «no podemos generar esto, prueba con otra foto».

Siguientes pasos

La misma forma de solicitud se aplica a otros modelos de imagen de HiAPI, por lo que el cliente que construyas aquí se convertirá en la plantilla para el resto de tu tubería. Una vez que la llamada de dos imágenes sea estable, explora el catálogo de modelos para ver qué más encaja en tu flujo de trabajo: los patrones de autenticación, manejo de errores y almacenamiento se aplican tal cual.

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