Search docs

Search the TryOnCloud API docs

Referencia de la API

Generar una prueba de ajuste

POST /api/v1/generate: se introducen una prenda y una persona, y se obtiene un archivo PNG final.

Los ejemplos de código, los puntos finales y los códigos de error son los mismos en todos los idiomas.

POST https://www.tryoncloud.com/api/v1/generate

Envía una prenda y una persona, y recibirás la prueba de ajuste terminada como respuesta. Una solicitud, una imagen, sin encuestas.

Encabezados

EncabezadoValor
X-API-KEYTu clave, tk_dev_v1_... (obligatorio)
X-Mocktrue para el modo de prueba gratuito (opcional, equivalente a ?mock=true)
Idempotency-KeyOpcional. Tu propio valor único por cada intento (de 1 a 255 caracteres imprimibles). Un nuevo intento con la misma clave nunca se cobra dos veces. Véase Nuevos intentos e idempotencia.

Cuerpo

Envía multipart/form-data o application/json. Se requieren dos imágenes.

CampoTipoDescripción
garment_imagearchivoLa foto de la prenda. O bien, utiliza garment_url o garment_base64
garment_urlcadenaUna URL pública de imagen https. La descargamos en el servidor.
garment_base64cadenaImagen en Base64, con o sin el prefijo data:
person_imagearchivoLa foto del comprador. O utiliza person_base64
person_base64cadenaImagen en Base64, con o sin el prefijo data:
customer_idcadenaOpcional. Tu propio identificador para el usuario final, de hasta 128 caracteres. Búscalo en el panel de control y borra sus datos con la opción Borrar los datos de un cliente.

Las imágenes deben estar en formato JPEG, PNG, WebP o HEIC, con un tamaño máximo de 15 MB cada una. Se comprueba el contenido del archivo, no solo el nombre o el tipo declarado.

Parámetros de consulta

ParámetroDescripción
mock=trueModo de prueba: comprueba todo, no genera nada, no cobra nada, no almacena nada. Devuelve la imagen de la persona sin modificaciones.

Respuesta

200 OK. El cuerpo es la imagen final, Content-Type: image/png, de aproximadamente 1 megapíxel (la clase «1K»). Léelo como bytes; no lo analices como JSON.

Encabezado de respuestaSignificado
X-Request-IdIdentificador único de esta solicitud, presente en todas las respuestas, incluidas las de error. Indícalo al servicio de asistencia.
X-RateLimit-Limit / X-RateLimit-RemainingTu límite por minuto y lo que te queda en el minuto actual
X-Credit-Was-Free1 si esta prueba ha consumido tu saldo gratuito, 0 si ha consumido créditos comprados
X-Result-IdSolo si el almacenamiento de resultados está activado en tu cuenta. Úsalo junto con la opción Eliminar un resultado.
X-Mock1 en las respuestas del modo de prueba
X-CostumeSolo para cuentas con el modo «costume» activado

Los errores devuelven un objeto JSON { "error": "...", "code": "..." }. Véase Errores.

Reintentos e idempotencia

Las redes pierden la conexión. Para volver a intentarlo de forma segura, envía un encabezado Idempotency-Key con un valor que generes para cada intento (por ejemplo, un UUID) y reutilízalo únicamente para los reintentos de ese mismo intento. Las claves se conservan durante 24 horas por cada clave de API.

¿Qué ocurre?Respuesta
Primera solicitudFunciona con normalidad
Vuelve a intentarlo mientras el primero aún se está ejecutando409 IDEMPOTENCY_IN_PROGRESS con Retry-After; no se ha cobrado nada
Vuelve a intentarlo una vez que haya salido bien409 IDEMPOTENCY_REPLAY, sin cargo alguno. La imagen se incluía en la primera respuesta; con el almacenamiento de resultados activado, result_id la identifica.
Vuelve a intentarlo después de que haya falladoSe vuelve a realizar (el intento fallido se reembolsó)
La misma clave, imágenes diferentes409 IDEMPOTENCY_MISMATCH

Sin el encabezado, cada solicitud supone una nueva prueba.

Ejemplos

en varias partes (archivos)

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -o result.png

JSON (URL de la prenda + persona en base64)

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"garment_url\":\"https://cdn.yourstore.com/shirt.jpg\",\"person_base64\":\"$(base64 -w0 person.jpg)\"}" \
  -o result.png

Node.js, versión 18 o superior

js
import { readFile, writeFile } from "node:fs/promises"

const form = new FormData()
form.append("garment_image", new Blob([await readFile("shirt.jpg")]), "shirt.jpg")
form.append("person_image", new Blob([await readFile("person.jpg")]), "person.jpg")

const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
  method: "POST",
  headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
})
if (!res.ok) {
  const { error, code } = await res.json()
  throw new Error(`${code}: ${error}`)
}
await writeFile("result.png", Buffer.from(await res.arrayBuffer()))

Facturación

  • Si la clave API tiene un límite de crédito mensual y se alcanza dicho límite, la solicitud se rechaza con el código de error 402 KEY_LIMIT_REACHED hasta el día 1 (UTC). Establece los límites al crear una clave en la página Claves API.
  • Cada prueba satisfactoria consume un crédito.
  • Las generaciones fallidas (422, 500) se reembolsan automáticamente.
  • El modo de prueba es siempre gratuito.
  • Las cuentas que han comprado créditos gastan los créditos adquiridos. Las cuentas que no lo han hecho gastan la asignación gratuita.