Search docs

Search the TryOnCloud API docs

Riferimento API

Genera una simulazione di prova

POST /api/v1/generate: in ingresso un capo d'abbigliamento e una persona, in uscita un file PNG finito.

Gli esempi di codice, gli endpoint e i codici di errore sono gli stessi in ogni linguaggio.

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

IntestazioneValore
X-API-KEYLa tua chiave, tk_dev_v1_... (obbligatoria)
X-Mocktrue per la modalità di prova gratuita (facoltativo, equivalente a ?mock=true)
Idempotency-KeyFacoltativo. 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

Corpo

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

CampoTipoDescrizione
garment_imagefileLa foto del capo. Oppure usa garment_url o garment_base64
garment_urlstringaUn URL pubblico di un'immagine https. Lo scarichiamo lato server
garment_base64stringaImmagine in formato Base64, con o senza il prefisso data:
person_imagefileLa foto dell'acquirente. Oppure usa person_base64
person_base64stringaImmagine in formato Base64, con o senza il prefisso data:
customer_idstringaFacoltativo. 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.

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

ParametroDescrizione
mock=trueModalità 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 rispostaSignificato
X-Request-IdID univoco di questa richiesta, presente in ogni risposta, comprese quelle di errore. Da indicare al servizio di assistenza
X-RateLimit-Limit / X-RateLimit-RemainingIl tuo limite al minuto e il tempo rimanente nel minuto corrente
X-Credit-Was-Free1 se questa prova ha utilizzato la tua quota gratuita, 0 se ha utilizzato i crediti acquistati
X-Result-IdSolo se l'archiviazione dei risultati è abilitata sul tuo account. Utilizzala insieme alla funzione Elimina un risultato
X-Mock1 sulle risposte in modalità di prova
X-CostumeSolo per gli account con la modalità "costume" attivata

Gli errori restituiscono un oggetto JSON { "error": "...", "code": "..." }. Vedi la sezione Errori.

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 succedeRisposta
Prima richiestaFunziona normalmente
Riprovare mentre il primo è ancora in esecuzione409 IDEMPOTENCY_IN_PROGRESS con Retry-After, nessun addebito
Riprova dopo che l'operazione è andata a buon fine409 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 fineSi ripete (il tentativo fallito è stato rimborsato)
Stessa chiave, immagini diverse409 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.