Integración de la API de Google Virtual Try-On: imagen de persona e imagen de prenda

Colocar cada una de las dos imágenes en el campo correcto da un punto de partida claro para la integración. La foto de la persona va en person_image_url y la imagen de la prenda en product_image_url; si pones la foto de la persona en el campo de la prenda, cambiarás el significado de la entrada de la tarea.

TL;DR

Google Virtual Try-On cuesta $0.1075 por imagen; consulta precios y presupuesto. Usa la interfaz /v1/tasks de HiAPI: envía la tarea para obtener el taskId y luego consulta el resultado. No se necesita prompt.

Preparación de las entradas y campos

Elige una foto frontal de una sola persona, con el contorno del cuerpo lo más claro posible; para la prenda, usa una imagen plana o colgada con fondo limpio y bordes completos. Las dos direcciones de imagen permanentes del ejemplo siguiente corresponden a la persona A y a una camiseta de rayas rojas y blancas, y puedes sustituirlas por tus propias direcciones de imagen públicas.

Campo	Forma de rellenarlo
person_image_url	Obligatorio; URL HTTP(S) pública de la foto de la persona
product_image_url	Obligatorio; URL HTTP(S) pública de la imagen del producto de prenda
num_images	Entero; escribe explícitamente 1, actualmente solo se admite una imagen

Asignar los casos de negocio a la solicitud

Para probar distintas prendas con la misma persona, fija person_image_url y sustituye product_image_url prenda por prenda; para mostrar distintas personas con la misma prenda, fija la imagen del producto y sustituye la imagen de la persona. Si necesitas varios candidatos para el mismo conjunto de imágenes, conserva las dos entradas, envía solicitudes por separado y sigue rellenando num_images: 1 en cada una. Se recomienda guardar en tus propios registros de tareas el número de producto y la versión de la imagen de la persona; no adivines la correspondencia solo por el nombre del archivo de resultado.

Tanto la persona como la prenda deben proporcionarse con direcciones de imagen HTTP(S) accesibles públicamente; no se admiten rutas locales de disco ni data URI como URL de imagen. Que la imagen sea visible en el navegador con sesión iniciada no significa que otros servicios puedan leerla; antes de enviar, comprueba el enlace sin depender de una sesión autenticada. Se recomienda confirmar que devuelve la imagen en sí y no una página de álbum ni una página de aviso de permisos, y mantener la imagen accesible durante la lectura de la tarea.

Si la foto de la persona oculta el bajo de la prenda o las manos se solapan en gran parte con la ropa, considera primero cambiar a una foto con límites más claros. Para la imagen de la prenda, prioriza una imagen plana o colgada de una sola pieza y con bordes completos, y evita tomar de nuevo el resultado de un conjunto puesto como si fuera una imagen de producto independiente. Los campos públicos no ofrecen ajustes de protección local, de puños ni de bloqueo de zapatos, y no se pueden expresar esos requisitos añadiendo campos personalizados.

Elegir imágenes claras es un método de trabajo; si la interfaz acepta la imagen y si la expresión del producto es precisa deben comprobarse por separado. Este artículo no añade para Try-On promesas sin evidencia sobre tamaño de archivo, límite de píxeles ni dimensiones de salida; tampoco se pueden aplicar directamente los límites de entrada de otros modelos de imagen.

Enviar la tarea: cURL

A continuación, un ejemplo de Bash/cURL. Primero configura HIAPI_API_KEY en el entorno de ejecución; la URL de imagen de la solicitud se puede sustituir y la clave se mantiene en el entorno del servidor.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

Un envío correcto devuelve data.taskId. Guarda este valor para consultas posteriores.

Consultar la tarea y guardar el resultado

Coloca el número de tarea en TASK_ID y consulta:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Cuando la tarea tenga data.status=success, obtén la imagen desde data.output[0].url y guárdala. Para negocios en funcionamiento continuo, puedes configurar callback.url y callback.when: "final" en el nivel superior de la solicitud de envío para recibir la notificación de finalización, y deduplicar por taskId; tanto el éxito como el fallo pueden activar la notificación. El método de consulta es adecuado para depuración y comprobaciones posteriores.

Polling, callback y gestión de tiempos de espera

Enviar y consultar son dos cosas distintas. Después de obtener data.taskId, regístralo junto con las entradas de esta vez y luego consulta GET /v1/tasks/:id. Mientras no haya alcanzado el estado final, sigue esperando y no sustituyas la consulta por otro POST. El intervalo de polling y el límite de espera del negocio los define tu aplicación; este artículo no ofrece un tiempo medio ni un plazo de finalización fijo que se pueda prometer; el tiempo de espera de red del ejemplo tampoco constituye una garantía de duración del servicio.

Que una solicitud de consulta agote el tiempo de espera solo indica que esta lectura no se completó a tiempo. Conserva el número de tarea y vuelve a consultar la misma tarea más tarde. Si la solicitud de envío en sí agota el tiempo de espera y no se obtuvo el número, existe incertidumbre sobre si el servidor ya la aceptó: conserva la hora de envío y el contenido de la solicitud, revisa primero los registros de tareas y luego decide si reenviar. No interpretes una excepción del cliente directamente como un fallo de la tarea ni prometas que las solicitudes repetidas se fusionarán automáticamente.

La configuración del callback va en el nivel superior del cuerpo de la solicitud, al mismo nivel que model e input, y no debe meterse dentro de la entrada del modelo. Al configurar callback.url, usa también callback.when: "final". La notificación de finalización puede corresponder a un éxito o a un fallo, así que tras recibirla hay que comprobar el estado. La consulta y el callback pueden procesar la misma tarea, por lo que el lado del negocio debe deduplicar por taskId para evitar descargas repetidas o activaciones posteriores duplicadas. Aquí se describe el método de procesamiento de la aplicación; no se asume que el callback llegue necesariamente en un tiempo determinado.

Después de data.status=success, confirma que data.output contiene realmente una dirección de resultado legible y luego descarga la imagen. Si devuelve fail, guarda el mensaje de error y corrige la solicitud según su contenido; no adivines a partir de un solo estado si se debe a una imagen demasiado grande, a un fallo de red u otra causa concreta. Ante un estado inesperado o la falta de salida, conserva la respuesta y vuelve a consultar; no tomes un resultado vacío como una entrega exitosa.

También hay que separar el fallo de descarga del fallo de generación. Si la tarea ya tuvo éxito pero el archivo no se guardó bien, primero vuelve a leer o descargar el resultado existente y evita rehacer la imagen directamente. Al archivar, conserva el número de tarea, la correspondencia de entradas y la ubicación del archivo final; solo así podrás encontrar después con precisión de qué solicitud proviene cada imagen. El "tiempo de espera agotado" que se muestra al usuario debe significar que la interfaz actual deja de esperar, no que se declare por iniciativa propia que la tarea del servidor se ha cancelado.

Ejemplo de envío en Python

El entorno necesita tener instalado requests. Aquí timeout=60 es el límite de espera de la solicitud de red del cliente, no el tiempo de generación de la imagen.

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

Antes de enviar y comprobación del resultado

La interfaz no necesita prompt. No rellenes num_images con 2 o 4; si necesitas imágenes candidatas, lanza solicitudes por separado. Antes de enviar, comprueba que las dos imágenes se puedan leer públicamente y que los campos no estén intercambiados. Si recibes un estado de fallo, lee la información devuelta y corrige la entrada; no reenvíes una y otra vez sin cambios.

Validar las imágenes devueltas según el uso del producto

Primero compara el resultado con la imagen de la persona y revisa el rostro, el peinado, la postura, el fondo y los pantalones y zapatos que no deberían cambiar. Luego contrasta con la imagen de la prenda el color, el tipo de cuello, el largo de manga, el estampado y el bajo. En la camiseta de rayas hay que mirar cómo se conectan las rayas horizontales en el pecho y las mangas; en el vestido, los tirantes, el escote con caída y los pliegues cerca de las manos; en la camisa, si los puños están enrollados y si el bajo está metido en la cintura del pantalón. Estas comprobaciones provienen de los cambios visibles en los casos y no garantizan que otras entradas solo presenten estos cambios.

"El archivo se ha descargado" y "la imagen se puede usar en la página de producto" deben registrarse por separado. Aunque el resultado se devuelva con éxito, todavía pueden aparecer cambios fuera de la ropa, y el estado de la interfaz no puede sustituir automáticamente la validación humana. Si el defecto proviene de una oclusión en la entrada, cambia primero la entrada y vuelve a intentarlo; si el producto debe mostrar un largo de manga concreto o un accesorio fijo, primero determina si el resultado actual cumple esa restricción, y no ignores los detalles del producto solo porque el conjunto se vea natural.

Al añadir candidatos para el mismo conjunto de entradas, conserva los resultados anteriores para comparar y no sobrescribas los archivos antiguos con los nuevos. Al elegir, indica el motivo de aceptación o rechazo para facilitar el tratamiento de productos similares en el futuro. Las imágenes solo sirven para observar la apariencia; la talla real y la sensación al llevarla requieren todavía información de tallas de la prenda y pruebas de personas reales.

Preguntas frecuentes

¿La foto de la persona y la imagen de la prenda pueden compartir un campo?

No. La foto de la persona usa person_image_url y la imagen de la prenda usa product_image_url.

¿Hay que añadir el parámetro prompt?

No. La interfaz no tiene campo de prompt; la prueba virtual la determinan las dos imágenes de entrada.

¿Por qué escribir explícitamente num_images: 1?

Actualmente solo se admite una imagen de resultado; escribirlo explícitamente permite que el número de imágenes de la solicitud corresponda directamente al presupuesto de $0.1075 por imagen.

¿Con obtener el taskId ya se puede leer la imagen?

Todavía hay que consultar la tarea o recibir la notificación; después de que la tarea tenga data.status=success, obtén la imagen desde data.output[0].url.

Seguir leyendo

Precios y presupuesto · Integración de la API · Casos y selección de imágenes · Google Virtual Try-On

Si necesitas elegir entre la prueba virtual de ropa o un método de edición de imágenes general, consulta la comparación entre Google Virtual Try-On y Seedream 5.0 Lite y revisa punto por punto la ropa, los zapatos y la apariencia de la persona.