Passer au contenu principal
Configurez le workspace d’un nouveau client depuis votre propre système, d’un workspace vide jusqu’à un premier run, avec l’API REST. Le workspace reste en DRAFT pendant que vous le configurez : rien n’est suivi ni facturé tant que vous ne l’avez pas activé et lancé un run.

Avant de commencer

  • Une offre Business, Agency Business ou Enterprise, et un jeton d’API dont l’accès en écriture a été activé par un Propriétaire ou un Manager. Consultez Écrire des données.
  • Un endpoint HTTPS public si vous voulez recevoir l’événement run.completed. Sinon, interrogez le run.
  • Assez de crédits pour le premier run. Vérifiez avec Crédits.
Toutes les valeurs ci-dessous sont synthétiques. Chaque POST exige un Idempotency-Key unique, et chaque PATCH exige If-Match avec l’ETag que vous avez lu en dernier.

Étapes

1

Créer le workspace en DRAFT

Conservez workspace.id comme BRAND_ID. Le workspace est en DRAFT, et l’en-tête ETag porte sa version.
2

Créer des Topics et des Tags

Conservez topic.id comme TOPIC_ID et tag.id comme TAG_ID. Consultez Créer un Topic et Créer un Tag.
3

Créer des prompts

Créez un prompt par requête. Les prompts suivis ajoutent une consommation récurrente de crédits. Consultez Créer un prompt.
4

Configurer le suivi

Lisez Obtenir le suivi pour connaître les modèles sélectionnés et l’ETag. Prévisualisez le changement avec dryRun, puis enregistrez-le. Quand aucun réglage n’existe encore, le premier ETag est "0".
Répétez la requête sans dryRun pour enregistrer. Consultez Mettre à jour le suivi.
5

S’abonner à run.completed

Créez un endpoint de webhook d’intégration limité au nouveau workspace. Conservez le secret renvoyé : il n’est affiché qu’une fois.
Vérifiez chaque envoi avec Vérifier les signatures.
6

Activer le workspace

Relisez le workspace pour obtenir son ETag actuel, puis passez-le à LIVE. Cet exemple suppose que l’ETag lu est "2".
L’activation ne lance jamais de génération. Un workspace au-delà de la limite de l’offre renvoie 409 QUOTA_EXCEEDED. Consultez Mettre à jour un workspace.
7

Estimer, puis lancer le premier run

Vérifiez sufficientCredits dans l’estimation avant de lancer. La requête de lancement renvoie 202 avec un en-tête Location et réserve les crédits prévus. Consultez Estimer un run et Lancer un run.
8

Attendre run.completed

Votre endpoint reçoit un événement run.completed signé lorsque le run atteint un état final :
Dédupliquez sur id : la livraison se fait au moins une fois. Un statut COMPLETED_WITH_WARNINGS signifie que certaines réponses ont échoué ; lisez donc counts. Sans webhook, interrogez Lister les runs.

Vérifier le résultat

Limites et retour en arrière

  • Rejouer une requête avec le même Idempotency-Key et le même corps renvoie la réponse d’origine pendant 24 heures. Utilisez une nouvelle clé pour une nouvelle opération logique, et lisez d’abord l’état après un résultat incertain.
  • 412 signifie que la ressource a changé depuis votre lecture. Relisez-la et réappliquez votre modification.
  • Un workspace LIVE ne peut pas revenir à DRAFT. Archivez-le avec status: ARCHIVED si le client part.
  • Il n’existe pas d’annulation de run dans l’API v1.

Voir aussi