Passer au contenu principal

​
Vue d’ensemble

Cette page décrit devis, réservation, exécution asynchrone, facturation et récupération des artefacts. Suivez les traitements longs par identifiant sans garder une connexion HTTP ouverte.

​
Comprendre exécution et facturation

POST /tools/quote renvoie version tarifaire, coût minimal et réservation maximale pour l’entrée. Le devis est gratuit, sans appel de services externes ni réservation de fonds. Gardez les mêmes tool et arguments et ajoutez :
  • priceVersion — Version tarifaire du devis
  • maximumChargeMicros — Réservation maximale du devis
Si les prix changent ou le plafond est insuffisant, la requête est rejetée avant traitement. Obtenez et vérifiez un nouveau devis.

​
Réserver et régler les frais

À l’acceptation, le maximum est temporairement réservé sur le solde prépayé en USD. À la fin, le coût réel est facturé et la part inutilisée restituée. Un échec ou une annulation peut entraîner la facturation de coûts externes déjà engagés. Aucun dépassement automatique du maximum réservé n’est facturé.

​
Suivre l’état

L’acceptation renvoie HTTP 202 et un identifiant. Suivez Retry-After: 5 et interrogez le même identifiant à au moins cinq secondes d’intervalle.

​
Éviter les doublons par idempotence

Une clé d’idempotence évite de créer plusieurs exécutions lors de renvois accidentels. Les appels payants à POST /tools/{tool} nécessitent Idempotency-Key. La clé comporte 8–128 caractères : lettres, chiffres, ., _, : ou -. Créez-en une par requête logique et conservez-la avec l’identifiant d’exécution.
  • Même clé API, même corps et même clé d’idempotence renvoient la même exécution.
  • Modifier le corps ou la clé API avec la même clé d’idempotence renvoie HTTP 409.
  • Après rupture de connexion, renvoyez sans modifier corps ni clé d’idempotence.
  • Renvoyer un traitement needs_review avec une nouvelle clé crée une autre exécution payante.
L’absence de réponse ne prouve pas que la requête n’a pas été acceptée. Ne créez pas de nouvelle clé si le résultat est inconnu.

​
Annuler une exécution

POST /tools/executions/{id}/cancel demande l’arrêt d’un travail non commencé. La clé créatrice ou un ADMIN du projet peut le demander. Un traitement externe déjà commencé et ses frais peuvent ne pas être annulables. Vérifiez cancelRequested, le status final et chargedMicros.

​
Récupérer les artefacts

Images, audio et vidéos générés figurent dans output.artifacts avec identifiant, format, taille, empreinte et expiration. Les fichiers et URL permanentes ne sont pas inclus dans le résultat. GET /tools/executions/{id}/artifacts/{artifactId}/download fournit une URL valable jusqu’à cinq minutes. Les fichiers stockés expirent après 30 jours. Même temporaires, ces URL donnent accès à des données privées. Ne les journalisez ni ne les publiez, et n’y ajoutez pas la clé Developer Platform.

​
Pages associées

Ces pages détaillent la première exécution et les endpoints.