# Genera una simulazione di prova

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

Invia un capo d'abbigliamento e una persona, riceverai in risposta l'immagine del capo indossato. Una richiesta, un'immagine, senza sondaggi.

## Intestazioni

| Intestazione | Valore |
|---|---|
| `X-API-KEY` | La tua chiave, `tk_dev_v1_...` (obbligatoria) |
| `X-Mock` | `true` per la modalità di prova gratuita (facoltativo, equivalente a `?mock=true`) |
| `Idempotency-Key` | Facoltativo. Un valore univoco per ogni prova (da 1 a 255 caratteri stampabili). Un nuovo tentativo con la stessa chiave non viene mai addebitato due volte. Vedi [Nuovi tentativi e idempotenza](#retries-and-idempotency) |

## Corpo

Invia `multipart/form-data` **o** `application/json`. Sono richieste due immagini.

| Campo | Tipo | Descrizione |
|---|---|---|
| `garment_image` | file | La foto del capo. Oppure usa `garment_url` o `garment_base64` |
| `garment_url` | stringa | Un URL pubblico di un'immagine `https`. Lo scarichiamo lato server |
| `garment_base64` | stringa | Immagine in formato Base64, con o senza il prefisso `data:` |
| `person_image` | file | La foto dell'acquirente. Oppure usa `person_base64` |
| `person_base64` | stringa | Immagine in formato Base64, con o senza il prefisso `data:` |
| `customer_id` | stringa | Facoltativo. Un ID personalizzato per l'utente finale, lungo al massimo 128 caratteri. Cercalo nella dashboard e cancella i suoi dati tramite l'opzione [Elimina i dati di un cliente](/docs/async#delete-a-customers-data). |

Le immagini devono essere in formato JPEG, PNG, WebP o HEIC, con una dimensione massima di 15 MB ciascuna. Viene verificato il contenuto del file, non solo il nome o il tipo dichiarato.

### Parametri di query

| Parametro | Descrizione |
|---|---|
| `mock=true` | Modalità di prova: verifica tutto, non genera nulla, non addebita nulla, non memorizza nulla. Restituisce l'immagine della persona senza modifiche |

## Risposta

**200 OK.** Il corpo del messaggio **è** l'immagine finale, `Content-Type: image/png`, di circa 1 megapixel (classe "1K"). Leggila come byte; non analizzarla come JSON.

| Intestazione di risposta | Significato |
|---|---|
| `X-Request-Id` | ID univoco di questa richiesta, presente in ogni risposta, comprese quelle di errore. Da indicare al servizio di assistenza |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` | Il tuo limite al minuto e il tempo rimanente nel minuto corrente |
| `X-Credit-Was-Free` | `1` se questa prova ha utilizzato la tua quota gratuita, `0` se ha utilizzato i crediti acquistati |
| `X-Result-Id` | Solo se l'archiviazione dei risultati è abilitata sul tuo account. Utilizzala insieme alla funzione [Elimina un risultato](/docs/delete-result) |
| `X-Mock` | `1` sulle risposte in modalità di prova |
| `X-Costume` | Solo per gli account con la modalità "costume" attivata |

Gli errori restituiscono un oggetto JSON `{ "error": "...", "code": "..." }`. Vedi [la sezione Errori](/docs/errors).

## Tentativi ripetuti e idempotenza

Le reti interrompono le connessioni. Per riprovare in modo sicuro, invia un’intestazione `Idempotency-Key` con un valore generato per ogni tentativo (ad esempio un UUID) e riutilizzala solo per i tentativi relativi a quello stesso tentativo. Le chiavi vengono conservate per 24 ore per ogni chiave API.

| Cosa succede | Risposta |
|---|---|
| Prima richiesta | Funziona normalmente |
| Riprovare mentre il primo è ancora in esecuzione | `409 IDEMPOTENCY_IN_PROGRESS` con `Retry-After`, nessun addebito |
| Riprova dopo che l'operazione è andata a buon fine | `409 IDEMPOTENCY_REPLAY`, nessun addebito. L'immagine era contenuta nella prima risposta; con la memorizzazione dei risultati attivata, `result_id` la identifica |
| Riprovare dopo che l'operazione non è andata a buon fine | Si ripete (il tentativo fallito è stato rimborsato) |
| Stessa chiave, immagini diverse | `409 IDEMPOTENCY_MISMATCH` |

Senza l'intestazione, ogni richiesta equivale a una nuova prova.

## Esempi

### multiparte (file)

```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 del capo + persona in 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, versione 18 o successive

```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()))
```

## Fatturazione

- Se la chiave API ha un limite di credito mensile e tale limite viene raggiunto, la richiesta viene rifiutata con il codice di errore `402 KEY_LIMIT_REACHED` fino al 1° del mese (UTC). Imposta i limiti al momento della creazione della chiave nella pagina **Chiavi API**.

- Ogni prova di abbigliamento riuscita consuma **un credito**.
- Le generazioni non riuscite (`422`, `500`) vengono rimborsate automaticamente.
- La modalità di prova è sempre gratuita.
- Gli account che hanno acquistato crediti utilizzano i crediti acquistati. Gli account che non li hanno acquistati utilizzano la quota gratuita.
