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
| Encabezado | Valor |
|---|---|
X-API-KEY | Tu clave, tk_dev_v1_... (obligatorio) |
X-Mock | true para el modo de prueba gratuito (opcional, equivalente a ?mock=true) |
Idempotency-Key | Opcional. 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.
| Campo | Tipo | Descripción |
|---|---|---|
garment_image | archivo | La foto de la prenda. O bien, utiliza garment_url o garment_base64 |
garment_url | cadena | Una URL pública de imagen https. La descargamos en el servidor. |
garment_base64 | cadena | Imagen en Base64, con o sin el prefijo data: |
person_image | archivo | La foto del comprador. O utiliza person_base64 |
person_base64 | cadena | Imagen en Base64, con o sin el prefijo data: |
customer_id | cadena | Opcional. 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ámetro | Descripción |
|---|---|
mock=true | Modo 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 respuesta | Significado |
|---|---|
X-Request-Id | Identificador único de esta solicitud, presente en todas las respuestas, incluidas las de error. Indícalo al servicio de asistencia. |
X-RateLimit-Limit / X-RateLimit-Remaining | Tu límite por minuto y lo que te queda en el minuto actual |
X-Credit-Was-Free | 1 si esta prueba ha consumido tu saldo gratuito, 0 si ha consumido créditos comprados |
X-Result-Id | Solo si el almacenamiento de resultados está activado en tu cuenta. Úsalo junto con la opción Eliminar un resultado. |
X-Mock | 1 en las respuestas del modo de prueba |
X-Costume | Solo 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 solicitud | Funciona con normalidad |
| Vuelve a intentarlo mientras el primero aún se está ejecutando | 409 IDEMPOTENCY_IN_PROGRESS con Retry-After; no se ha cobrado nada |
| Vuelve a intentarlo una vez que haya salido bien | 409 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 fallado | Se vuelve a realizar (el intento fallido se reembolsó) |
| La misma clave, imágenes diferentes | 409 IDEMPOTENCY_MISMATCH |
Sin el encabezado, cada solicitud supone una nueva prueba.
Ejemplos
en varias partes (archivos)
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.pngJSON (URL de la prenda + persona en base64)
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.pngNode.js, versión 18 o superior
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_REACHEDhasta 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.