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éponse | Le fichier PNG, dans la même requête | 202 avec un identifiant de tâche | 202 avec un identifiant de lot |
| Données d'entrée | Fichiers, base64 ou garment_url | Fichiers, base64 ou URL | garment_url et person_url par article |
| Résultat | Corps de la réponse | GET /results/:id, conservé pendant 7 jours | Idem, par article |
| Notification | Aucune nécessaire | Poll ou webhook | Webhook par élément, plus batch.completed |
| Crédits | Allocation gratuite ou crédits achetés | Crédits achetés | Cré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 :
| Champ | Description |
|---|---|
person_url | URL publique https de la photo de l'acheteur (alternative à un fichier ou à un code Base64) |
customer_id | Votre identifiant pour l'utilisateur final, 128 caractères maximum. Utilisé lors de la suppression d'un client |
metadata | Un 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_url | URL publique https permettant de recevoir les notifications generation.completed ou 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 Accepté
{
"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é :
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngUne 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 :
{
"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/:idrenvoie le nombre d'éléments et la liste complète de ceux-ci. DELETE /batches/:idannule 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.completedune fois que chaque élément a un résultat.
Webhooks
Nous envoyons une requête POST au format JSON vers votre 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 }
}É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> :
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).
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }Limites
| Création de tâches et de lots | Est pris en compte dans la limite de 300 requêtes par minute et par clé |
| Tâches asynchrones s'exécutant simultanément | 50 par compte (429 TOO_MANY_JOBS) ; les lots sont distincts |
| Taille du lot | 500 articles |
| Résultats | Conservé pendant 7 jours |
| Métadonnées | Objet JSON, 2 Ko |