Search docs

Search the TryOnCloud API docs

Référence de l'API

Tâches asynchrones, traitements par lots et webhooks

POST /api/v1/generations et /batches, webhooks signés, suppression de clients.

Les exemples de code, les points de terminaison et les codes d'erreur sont identiques dans tous les langages.

POST /generate est le moyen le plus simple d'effectuer un essai : une seule requête, et l'image s'affiche. Utilisez les tâches asynchrones lorsque vous ne souhaitez pas maintenir une connexion ouverte, et les traitements par lots pour les opérations liées au catalogue. Les deux utilisent le même moteur, ont le même coût et remboursent chaque essai qui échoue.

POST /generate (synchrone)POST /generations (asynchrone)POST /batches
RéponseLe fichier PNG, dans la même requête202 avec un identifiant de tâche202 avec un identifiant de lot
Données d'entréeFichiers, base64 ou garment_urlFichiers, base64 ou URLgarment_url et person_url par article
RésultatCorps de la réponseGET /results/:id, conservé pendant 7 joursIdem, par article
NotificationAucune nécessairePoll ou webhookWebhook par élément, plus batch.completed
CréditsAllocation gratuite ou crédits achetésCrédits achetésCrédits achetés, débités pour tous les éléments à la création du lot
Mode test?mock=true?mock=true?mock=true

Lancer une tâche asynchrone

POST https://www.tryoncloud.com/api/v1/generations

Les mêmes en-têtes et champs d'image que dans Générer, ainsi que :

ChampDescription
person_urlURL publique https de la photo de l'acheteur (alternative à un fichier ou à un code Base64)
customer_idVotre identifiant pour l'utilisateur final, 128 caractères maximum. Utilisé lors de la suppression d'un client
metadataUn objet JSON d'une taille maximale de 2 Ko, renvoyé tel quel lors de l'exécution de la tâche et dans les webhooks
webhook_urlURL publique https permettant de recevoir les notifications generation.completed ou 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 Accepté

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
}

Le traitement commence dès l'envoi de la réponse. Vos images sont traitées en mémoire et ne sont jamais enregistrées ; seul le résultat final est conservé, pendant 7 jours.

Consulter une offre d'emploi

GET https://www.tryoncloud.com/api/v1/generations/:id

status passe de queued à processing, puis à completed ou failed. Une tâche terminée dispose d'un result_url ; téléchargez-la à l'aide de votre clé :

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

Une tâche ayant échoué présente l'un des codes d'erreur suivants : error.code : CONTENT_FILTERED, GENERATION_FAILED ou INPUT_FETCH_FAILED. Le crédit est remboursé dans tous les cas.

Lots

POST https://www.tryoncloud.com/api/v1/batches, avec un corps JSON contenant jusqu'à 500 éléments :

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"
}
  • Un crédit est débité par article lors de la création du lot. Si votre solde est insuffisant, rien n'est créé (code 402 NO_CREDITS).
  • La requête GET /batches/:id renvoie le nombre d'éléments et la liste complète de ceux-ci.
  • DELETE /batches/:id annule les tâches qui n'ont pas encore démarré et procède à leur remboursement. Les tâches en cours d'exécution sont menées à terme.
  • Chaque élément envoie son propre webhook, et le lot envoie batch.completed une fois que chaque élément a un résultat.

Webhooks

Nous envoyons une requête POST au format JSON vers votre 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 }
}

Événements : generation.completed, generation.failed, batch.completed et webhook.test depuis le tableau de bord.

En-têtes : x-tryoncloud-event, x-tryoncloud-delivery-id (déduplication sur cet en-tête), x-tryoncloud-timestamp et x-tryoncloud-signature-v2.

Point de terminaison du compte. Au lieu d'envoyer l'webhook_url à chaque requête, enregistrez un point de terminaison dans le tableau de bord (Clés API > Webhooks) et sélectionnez les événements qu'il doit recevoir. L'webhook_url propre à chaque requête prévaut toujours. La commande Envoyer un événement de test envoie un événement signé webhook.test vers le point de terminaison enregistré.

Vérifiez chaque livraison. Votre clé de signature se trouve sur la même carte (montrez-la, copiez-la ou faites-la tourner). La signature est un HMAC-SHA256 de <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))
}

Répondez avec n'importe quel code 2xx dans les 8 secondes. Les autres réponses et les délais d'expiration font l'objet de nouvelles tentatives avec un délai d'attente (1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 24 heures). Les URL de webhook doivent être publiques (https) et utiliser le port standard ; les adresses privées et internes sont refusées, tant lors de l'enregistrement de l'URL que lors de l'envoi, et les redirections ne sont pas suivies.

Supprimer les données d'un client

DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id

Supprime tous les résultats enregistrés pour cet customer_id sur votre compte et efface cet identifiant de vos enregistrements. À utiliser lorsqu'un utilisateur final demande à être « oublié » (GDPR, DPDP).

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

Limites

Création de tâches et de lotsEst pris en compte dans la limite de 300 requêtes par minute et par clé
Tâches asynchrones s'exécutant simultanément50 par compte (429 TOO_MANY_JOBS) ; les lots sont distincts
Taille du lot500 articles
RésultatsConservé pendant 7 jours
MétadonnéesObjet JSON, 2 Ko