# Generar una prueba de ajuste

`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](#retries-and-idempotency). |

## 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.](/docs/async#delete-a-customers-data) |

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.](/docs/delete-result) |
| `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](/docs/errors).

## 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)

```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.
