Search docs

Search the TryOnCloud API docs

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
RespuestaEl archivo PNG, en la misma solicitud202 con un ID de trabajo202 con un identificador de lote
Datos de entradaArchivos, base64 o garment_urlArchivos, código base64 o URLgarment_url y person_url por artículo
ResultadoCuerpo de la respuestaGET /results/:id, se conserva durante 7 díasLo mismo, por unidad
NotificaciónNo es necesarioPoll o webhookWebhook por elemento, además de batch.completed
CréditosAsignación gratuita o créditos compradosCréditos compradosCré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:

CampoDescripción
person_urlURL pública https de la foto del comprador (alternativa a un archivo o a un código base64)
customer_idTu identificador de usuario final, de hasta 128 caracteres. Se utiliza para eliminar clientes.
metadataUn objeto JSON de hasta 2 KB, que se devuelve sin modificaciones tanto en la tarea como en los webhooks.
webhook_urlURL pública https para recibir generation.completed o generation.failed
bash
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

json
{
  "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:

bash
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.png

Una 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:

json
{
  "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/:id devuelve el recuento y todos los elementos.
  • DELETE /batches/:id cancela 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.completed una vez que todos los elementos tienen un resultado.

Webhooks

Enviamos un POST JSON a tu webhook_url:

json
{
  "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>:

js
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).

json
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }

Límites

Creación de trabajos y lotesSe contabiliza en el límite de 300 solicitudes por minuto por clave
Tareas asíncronas que se ejecutan al mismo tiempo50 por cuenta (429 TOO_MANY_JOBS); los lotes son independientes
Tamaño del lote500 artículos
ResultadosSe conserva durante 7 días
MetadatosObjeto JSON, 2 KB