Riferimento API
Operazioni asincrone, elaborazioni in batch e webhook
POST /api/v1/generations e /batches, webhook firmati, eliminazione dei clienti.
Gli esempi di codice, gli endpoint e i codici di errore sono gli stessi in ogni linguaggio.
POST /generate è il modo più semplice per eseguire una prova: basta una richiesta e l'immagine viene restituita. Utilizza i processi asincroni quando non vuoi mantenere aperta una connessione e i batch per il lavoro sul catalogo. Entrambi utilizzano lo stesso motore, hanno lo stesso costo e rimborsano ogni prova che non va a buon fine.
POST /generate (sincrono) | POST /generations (asincrono) | POST /batches | |
|---|---|---|---|
| Risposta | Il PNG, nella stessa richiesta | 202 con un ID lavoro | 202 con un ID batch |
| Dati in ingresso | File, base64 o garment_url | File, codici base64 o URL | garment_url e person_url per ogni articolo |
| Risultato | Corpo della risposta | GET /results/:id, conservato per 7 giorni | Idem, per articolo |
| Notifica | Non necessario | Polling o webhook | Webhook per ogni elemento, oltre a batch.completed |
| Crediti | Quota gratuita o crediti acquistati | Crediti acquistati | Crediti acquistati, addebitati per tutti gli elementi alla creazione del batch |
| Modalità di prova | ?mock=true | ?mock=true | ?mock=true |
Avvia un processo asincrono
POST https://www.tryoncloud.com/api/v1/generations
Stesse intestazioni e stessi campi immagine presenti in Genera, oltre a:
| Campo | Descrizione |
|---|---|
person_url | URL pubblico https della foto dell'acquirente (in alternativa a un file o a un codice base64) |
customer_id | Il tuo ID per l'utente finale, fino a 128 caratteri. Utilizzato per l'eliminazione del cliente |
metadata | Un oggetto JSON di dimensioni massime pari a 2 KB, restituito senza modifiche sia nel processo che nei webhook |
webhook_url | URL pubblico https per ricevere generation.completed o generation.failed |
curl -X POST https://www.tryoncloud.com/api/v1/generations \
-H "X-API-KEY: $TRYONCLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "garment_image=@shirt.jpg" \
-F "person_image=@person.jpg" \
-F "customer_id=shopper_123" \
-F "webhook_url=https://example.com/hooks/tryoncloud"202 Accettato
{
"id": "6f0e3c1a-0d6a-4f7e-9a7b-2b2a1d3c4e5f",
"object": "generation",
"status": "queued",
"mock": false,
"batch_id": null,
"customer_id": "shopper_123",
"metadata": null,
"result_id": null,
"result_url": null,
"error": null,
"created_at": "2026-11-18T10:00:00.000Z",
"completed_at": null
}L'elaborazione ha inizio non appena viene inviata la risposta. Le immagini vengono elaborate in memoria e non vengono mai salvate; viene conservato solo il risultato finale, per 7 giorni.
Verifica un'offerta di lavoro
GET https://www.tryoncloud.com/api/v1/generations/:id
Lo status passa da queued a processing, per poi diventare completed o failed. Un lavoro completato ha un result_url; scaricalo utilizzando la tua chiave:
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngUn'operazione non riuscita presenta uno dei seguenti codici di errore: error.code: CONTENT_FILTERED, GENERATION_FAILED o INPUT_FETCH_FAILED. In ogni caso, il credito viene rimborsato.
Lotti
POST https://www.tryoncloud.com/api/v1/batches con un corpo JSON contenente fino a 500 elementi:
{
"items": [
{ "garment_url": "https://cdn.example.com/kurta-1.jpg", "person_url": "https://cdn.example.com/model-a.jpg", "customer_id": "sku-1001" },
{ "garment_url": "https://cdn.example.com/saree-7.jpg", "person_url": "https://cdn.example.com/model-b.jpg" }
],
"webhook_url": "https://example.com/hooks/tryoncloud"
}- Al momento della creazione del lotto viene addebitato un credito per ogni articolo. Se il saldo è insufficiente, non viene creato nulla (codice
402 NO_CREDITS). GET /batches/:idrestituisce il numero di elementi e tutti gli elementi stessi.DELETE /batches/:idannulla le attività che non sono ancora state avviate e ne rimborsa il costo. Le attività in corso vengono portate a termine.- Ogni elemento invia il proprio webhook, mentre il batch invia
batch.completeduna volta che tutti gli elementi hanno un esito.
Webhook
Invieremo un request POST in formato JSON al tuo webhook_url:
{
"event": "generation.completed",
"created_at": "2026-11-18T10:00:21.000Z",
"data": { "id": "6f0e3c1a-...", "object": "generation", "status": "completed", "result_url": "https://www.tryoncloud.com/api/v1/results/...", "customer_id": "shopper_123", "metadata": null }
}Eventi: generation.completed, generation.failed, batch.completed e webhook.test dalla dashboard.
Intestazioni: x-tryoncloud-event, x-tryoncloud-delivery-id (effettuare la deduplicazione su questa), x-tryoncloud-timestamp e x-tryoncloud-signature-v2.
Endpoint dell'account. Anziché inviare l'webhook_url con ogni richiesta, salva un endpoint nella dashboard (Chiavi API > Webhook) e seleziona gli eventi che deve ricevere. L'webhook_url specificato nella richiesta ha sempre la precedenza. Invia un evento di prova firmato webhook.test all'endpoint salvato.
Verifica ogni consegna. Il tuo segreto di firma si trova sulla stessa scheda (mostralo, copialo o ruotalo). La firma è un HMAC-SHA256 di <timestamp>.<raw body>:
import crypto from "node:crypto"
export function verifyTryOnCloud(rawBody, headers, secret) {
const ts = headers["x-tryoncloud-timestamp"]
const sig = (headers["x-tryoncloud-signature-v2"] || "").replace("sha256=", "")
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // reject old deliveries
const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}Rispondere con qualsiasi codice 2xx entro 8 secondi. Le altre risposte e i timeout vengono riprovati con un backoff (1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore, 24 ore). Gli URL dei webhook devono essere pubblici https sulla porta standard; gli indirizzi privati e interni vengono rifiutati, sia al momento del salvataggio dell'URL che al momento dell'invio, e i reindirizzamenti non vengono seguiti.
Eliminare i dati di un cliente
DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id
Elimina tutti i risultati memorizzati relativi a quel customer_id dal tuo account e cancella l'ID dai tuoi registri. Utilizzalo quando un utente finale richiede il diritto all'oblio (GDPR, DPDP).
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }Limiti
| Creazione di lavori e lotti | Viene conteggiato ai fini del limite di 300 richieste al minuto per chiave |
| Processi asincroni in esecuzione contemporaneamente | 50 per account (429 TOO_MANY_JOBS); i batch sono separati |
| Dimensione del lotto | 500 articoli |
| Risultati | Conservato per 7 giorni |
| Metadati | Oggetto JSON, 2 KB |