Referencia de la API
Tareas asíncronas, lotes y webhooks
POST /api/v1/generations y /batches, webhooks firmados, eliminación de clientes.
Los ejemplos de código, los puntos finales y los códigos de error son los mismos en todos los idiomas.
POST /generate es la forma más sencilla de realizar una prueba de ajuste: una sola solicitud y se obtiene la imagen. Utiliza tareas asíncronas cuando no quieras mantener abierta una conexión, y procesamientos por lotes para el trabajo con catálogos. Ambos utilizan el mismo motor, tienen el mismo coste y reembolsan cada prueba de ajuste que falle.
POST /generate (síncrono) | POST /generations (asíncrono) | POST /batches | |
|---|---|---|---|
| Respuesta | El archivo PNG, en la misma solicitud | 202 con un ID de trabajo | 202 con un identificador de lote |
| Datos de entrada | Archivos, base64 o garment_url | Archivos, código base64 o URL | garment_url y person_url por artículo |
| Resultado | Cuerpo de la respuesta | GET /results/:id, se conserva durante 7 días | Lo mismo, por unidad |
| Notificación | No es necesario | Poll o webhook | Webhook por elemento, además de batch.completed |
| Créditos | Asignación gratuita o créditos comprados | Créditos comprados | Créditos comprados, se cobran todos los elementos al crear el lote |
| Modo de prueba | ?mock=true | ?mock=true | ?mock=true |
Iniciar una tarea asíncrona
POST https://www.tryoncloud.com/api/v1/generations
Los mismos encabezados y campos de imagen que en Generar, además de:
| Campo | Descripción |
|---|---|
person_url | URL pública https de la foto del comprador (alternativa a un archivo o a un código base64) |
customer_id | Tu identificador de usuario final, de hasta 128 caracteres. Se utiliza para eliminar clientes. |
metadata | Un objeto JSON de hasta 2 KB, que se devuelve sin modificaciones tanto en la tarea como en los webhooks. |
webhook_url | URL pública https para recibir generation.completed o generation.failed |
curl -X POST https://www.tryoncloud.com/api/v1/generations \
-H "X-API-KEY: $TRYONCLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "garment_image=@shirt.jpg" \
-F "person_image=@person.jpg" \
-F "customer_id=shopper_123" \
-F "webhook_url=https://example.com/hooks/tryoncloud"202 Aceptadas
{
"id": "6f0e3c1a-0d6a-4f7e-9a7b-2b2a1d3c4e5f",
"object": "generation",
"status": "queued",
"mock": false,
"batch_id": null,
"customer_id": "shopper_123",
"metadata": null,
"result_id": null,
"result_url": null,
"error": null,
"created_at": "2026-11-18T10:00:00.000Z",
"completed_at": null
}El proceso comienza en cuanto se envía la respuesta. Tus imágenes se procesan en memoria y nunca se almacenan; solo se conserva el resultado final, durante 7 días.
Consultar una oferta de empleo
GET https://www.tryoncloud.com/api/v1/generations/:id
status pasa de queued a processing y, a continuación, a completed o failed. Un trabajo completado tiene result_url; descárgalo con tu clave:
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngUna tarea fallida tiene el código de error error.code: CONTENT_FILTERED, GENERATION_FAILED o INPUT_FETCH_FAILED. En todos los casos se reembolsa el crédito.
Lotes
POST https://www.tryoncloud.com/api/v1/batches con un cuerpo JSON de hasta 500 elementos:
{
"items": [
{ "garment_url": "https://cdn.example.com/kurta-1.jpg", "person_url": "https://cdn.example.com/model-a.jpg", "customer_id": "sku-1001" },
{ "garment_url": "https://cdn.example.com/saree-7.jpg", "person_url": "https://cdn.example.com/model-b.jpg" }
],
"webhook_url": "https://example.com/hooks/tryoncloud"
}- Al crear el lote, se deduce un crédito por cada artículo. Si tu saldo es demasiado bajo, no se crea nada (código de error
402 NO_CREDITS). GET /batches/:iddevuelve el recuento y todos los elementos.DELETE /batches/:idcancela los trabajos que aún no han comenzado y devuelve el importe correspondiente. Los trabajos en ejecución se completan.- Cada elemento envía su propio webhook, y el lote envía
batch.completeduna vez que todos los elementos tienen un resultado.
Webhooks
Enviamos un POST JSON a tu webhook_url:
{
"event": "generation.completed",
"created_at": "2026-11-18T10:00:21.000Z",
"data": { "id": "6f0e3c1a-...", "object": "generation", "status": "completed", "result_url": "https://www.tryoncloud.com/api/v1/results/...", "customer_id": "shopper_123", "metadata": null }
}Eventos: generation.completed, generation.failed, batch.completed y webhook.test desde el panel de control.
Encabezados: x-tryoncloud-event, x-tryoncloud-delivery-id (eliminar duplicados en este), x-tryoncloud-timestamp y x-tryoncloud-signature-v2.
Punto final de la cuenta. En lugar de enviar webhook_url con cada solicitud, guarda un punto final en el panel de control (Claves API > Webhooks) y selecciona los eventos que debe recibir. La webhook_url de la propia solicitud siempre tiene prioridad. La función Enviar eventos de prueba envía un evento firmado webhook.test al punto final guardado.
Comprueba cada entrega. Tu secreto de firma se encuentra en la misma tarjeta (muéstralo, cópialo o gíralo). La firma es un HMAC-SHA256 de <timestamp>.<raw body>:
import crypto from "node:crypto"
export function verifyTryOnCloud(rawBody, headers, secret) {
const ts = headers["x-tryoncloud-timestamp"]
const sig = (headers["x-tryoncloud-signature-v2"] || "").replace("sha256=", "")
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // reject old deliveries
const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}Responde con cualquier código 2xx en un plazo de 8 segundos. Las demás respuestas y los tiempos de espera se reintentan con un intervalo de espera (1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas). Las URL de los webhooks deben ser públicas https en el puerto estándar; se rechazan las direcciones privadas e internas, tanto al guardar la URL como al enviarla, y no se siguen las redirecciones.
Eliminar los datos de un cliente
DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id
Elimina todos los resultados almacenados correspondientes a ese customer_id en tu cuenta y borra el identificador de tus registros. Úsalo cuando un usuario final solicite el derecho al olvido (GDPR, DPDP).
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }Límites
| Creación de trabajos y lotes | Se contabiliza en el límite de 300 solicitudes por minuto por clave |
| Tareas asíncronas que se ejecutan al mismo tiempo | 50 por cuenta (429 TOO_MANY_JOBS); los lotes son independientes |
| Tamaño del lote | 500 artículos |
| Resultados | Se conserva durante 7 días |
| Metadatos | Objeto JSON, 2 KB |