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