Search docs

Search the TryOnCloud API docs

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
RispostaIl PNG, nella stessa richiesta202 con un ID lavoro202 con un ID batch
Dati in ingressoFile, base64 o garment_urlFile, codici base64 o URLgarment_url e person_url per ogni articolo
RisultatoCorpo della rispostaGET /results/:id, conservato per 7 giorniIdem, per articolo
NotificaNon necessarioPolling o webhookWebhook per ogni elemento, oltre a batch.completed
CreditiQuota gratuita o crediti acquistatiCrediti acquistatiCrediti 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:

CampoDescrizione
person_urlURL pubblico https della foto dell'acquirente (in alternativa a un file o a un codice base64)
customer_idIl tuo ID per l'utente finale, fino a 128 caratteri. Utilizzato per l'eliminazione del cliente
metadataUn oggetto JSON di dimensioni massime pari a 2 KB, restituito senza modifiche sia nel processo che nei webhook
webhook_urlURL pubblico https per ricevere generation.completed o generation.failed
bash
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

json
{
  "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:

bash
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.png

Un'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:

json
{
  "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/:id restituisce il numero di elementi e tutti gli elementi stessi.
  • DELETE /batches/:id annulla 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.completed una volta che tutti gli elementi hanno un esito.

Webhook

Invieremo un request POST in formato JSON al tuo webhook_url:

json
{
  "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>:

js
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).

json
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }

Limiti

Creazione di lavori e lottiViene conteggiato ai fini del limite di 300 richieste al minuto per chiave
Processi asincroni in esecuzione contemporaneamente50 per account (429 TOO_MANY_JOBS); i batch sono separati
Dimensione del lotto500 articoli
RisultatiConservato per 7 giorni
MetadatiOggetto JSON, 2 KB