FASHN Try-On v1.6 API: ejemplos de solicitudes curl y Python listos para usar

FASHN Try-On v1.6 es un modelo de probador virtual (image-to-image) disponible en hiapi. Le proporcionas dos imágenes —una foto de una persona y una foto de una prenda— y devuelve una imagen compuesta del resultado puesto. Este artículo es una guía práctica de fashn try-on api orientada a desarrolladores: incluye una solicitud real a /v1/tasks que ejecuté de principio a fin, el schema de entrada completo verificado contra el validador de parámetros en línea, y detalles de producción que no aparecen en la tabla de parámetros.

Página del modelo y experiencia en línea: FASHN Try-On v1.6.

1. Qué vas a construir + requisitos previos

Todo el flujo es el patrón estándar de tareas asíncronas: un POST para crear la tarea, luego sondeo (polling) hasta que la tarea alcance un estado terminal, y finalmente la descarga de la imagen de salida.

Necesitas:

• Una API key (sk-...), que puedes obtener en inicio rápido de hiapi.
• Dos URL de imágenes públicamente accesibles: la foto de la persona para model_image y la foto de la prenda para garment_image.

2. Ejemplo mínimo funcional

Crear la tarea (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

Respuesta — es una tarea aceptada, no una imagen final:

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image y garment_image son los únicos campos obligatorios; el resto de campos tienen valores por defecto.

Sondear el resultado (curl)

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

Cuando la tarea finaliza, obtienes data.status: "success" y la imagen se encuentra en data.output[0].url:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

El campo expireAt es importante aquí: la salida se almacena en almacenamiento temporal (TTL de aproximadamente 7 días). Descarga o reubica esos bytes de inmediato — no enlaces directamente a la URL.

Ejecución de extremo a extremo en Python

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. Schema de entrada (verificado contra el validador en línea)

fashn-tryon-v1.6 utiliza un schema cerrado: cualquier campo que no aparezca a continuación será rechazado, así que no puedes incluir parámetros adicionales nativos de FASHN que hiapi no expone.

Campo	¿Obligatorio?	Tipo	Valores aceptables
model_image	Sí	string (URL)	Foto de la persona
garment_image	Sí	string (URL)	Foto de la prenda
category	No	enum	tops, bottoms, one-pieces, auto
mode	No	enum	performance, balanced, quality
garment_photo_type	No	enum	auto, model, flat-lay
output_format	No	enum	png, jpeg
seed	No	integer	Para reproducibilidad
segmentation_free	No	boolean	—

Cómo lo confirmé: enviar {"model":"fashn-tryon-v1.6","input":{}} devuelve

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

Cada valor de enumeración anterior se confirmó enviando un valor no válido, por ejemplo mode: value must be one of 'performance', 'balanced', 'quality'. Pasar num_samples, num_images o cualquier campo fuera de la tabla devuelve additional properties '...' not allowed — no hay opción de múltiples muestras. Una solicitud devuelve una imagen; si quieres resultados distintos, varía el seed entre llamadas.

4. Prácticas para producción

• La validación ocurre antes del cobro. Una entrada no válida devuelve HTTP 400, con cuerpo de respuesta {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}, y no se crea ninguna tarea — las solicitudes mal formadas no generan cargos. Una solicitud válida devuelve code:200 junto con un taskId.
• Vuelve a sondear, no a reenviar. Cada POST /v1/tasks crea una nueva tarea (facturable). Si una solicitud de sondeo expira, sigue sondeando el taskId que ya tienes; una respuesta perdida no significa que la tarea haya fallado.
• Usa callbacks en lugar de sondeo. Para escenarios por lotes, puedes registrar un callback para que hiapi te notifique cuando la tarea alcance su estado final, sin tener que sondear tú mismo — consulta los campos específicos en la referencia de la API asíncrona unificada. El ejemplo anterior utiliza sondeo.

5. Cómo fue una ejecución real

Ejecuté la solicitud mínima anterior —una foto de persona de 768×1152 y una imagen de prenda de 768×1152, omitiendo mode y category:

• Latencia: aproximadamente 13 segundos desde created hasta completed en el objeto de la tarea.
• Salida: un único PNG de 768×1152, es decir, una imagen vertical. La página del modelo indica que el tamaño de salida sigue a la foto de la persona (en sus ejecuciones verificadas se midieron 972×1296 y 768×1152), lo cual coincide con esta ejecución — no hay campos width/height/aspect_ratio, por lo que las dimensiones de la foto de la persona determinan el tamaño de salida.
• Ruta de estados: durante el sondeo se mostró primero archiving y después success; storage era temp.
• Los valores por defecto funcionan. Omitir mode y category sigue funcionando, así que esas dos URL de imágenes son efectivamente las únicas entradas obligatorias — el modelo identifica automáticamente el tipo de prenda.

La facturación se calcula según el número de imágenes de salida y no varía según el mode que elijas; consulta la página de precios para conocer la tarifa actual.

Enlaces relacionados

• Página del modelo FASHN Try-On v1.6 y experiencia en línea
• Referencia de la API asíncrona (de tareas) unificada
• Inicio rápido — obtener una API key
• Precios

Preguntas frecuentes

¿Qué campos son obligatorios? Solo model_image y garment_image, y ambos deben ser URL públicamente accesibles.

¿Puedo generar varias variantes en una sola llamada? No — num_samples y num_images son rechazados por el schema. Una solicitud devuelve una imagen; varía el seed entre llamadas para obtener resultados distintos.

¿Cómo controlo el tamaño de salida? No puedes configurarlo directamente. El resultado sigue las dimensiones de la foto de la persona — mi entrada de 768×1152 produjo una salida de 768×1152.

¿Cuánto tiempo es válida la URL del resultado? La salida está en almacenamiento temporal, con un expireAt (aproximadamente 7 días). Descarga esos bytes de inmediato.

¿El modo de calidad cambia el precio? No — ya sea performance, balanced o quality, se cobra según el número de imágenes de salida.