Démarrage rapide

Choisissez un modèle et un endpoint dans le Catalog, puis envoyez les entrées requises par l’endpoint. Cet exemple démarre une tâche Flux 2 de texte vers image :

Une requête asynchrone acceptée renvoie 202 Accepted avec un identifiant de tâche :

Stockez id avec votre enregistrement applicatif. C’est l’identifiant stable utilisé pour l’interrogation, le support et la réconciliation des callbacks.

Les endpoints de création de tâche acceptent un en-tête optionnel Idempotency-Key avec une valeur opaque pouvant aller jusqu’à 512 caractères. Générez une valeur par tâche logique et conservez-la avec la requête jusqu’à ce que vous sachiez si elle a été acceptée.

Si un délai d’attente ou une panne de connexion laisse le résultat inconnu, réessayez la même requête de création de tâche avec la même clé. RunAPI retourne la tâche originale au lieu d’en créer une nouvelle et de la facturer. La réutilisation d’une clé avec une requête de création de tâche différente retourne 409 Conflict. Générez une nouvelle clé pour une nouvelle tâche intentionnelle, et n’utilisez pas X-Client-Request-Id comme clé.

Les endpoints synchrones lents maintiennent normalement la connexion ouverte et retournent la même réponse terminale qu’auparavant. Aucune modification d’interrogation n’est requise pour les intégrations existantes.

Pour un budget de connexion intentionnellement plus court, envoyez Prefer: wait=N. Si la tâche est toujours en cours après ce budget explicite, RunAPI renvoie 202 Accepted avec le même id de tâche, une URL Location opaque pour la récupération, et Retry-After pour le délai de requête suggéré. Suivez Location exactement plutôt que de construire une URL de résultat. Un résultat de tâche terminée préserve le statut HTTP terminal, les en-têtes autorisés, le type de contenu et le corps ; décodez response.body selon response.content_type, qui n’est pas toujours JSON.

Ajoutez l’identifiant de tâche au même chemin de point de terminaison :

Continuez tant que status est processing. Utilisez un backoff borné entre les requêtes plutôt qu’une interrogation continue. Une tâche devient terminale lorsque son statut est completed ou failed.

Une réponse completed inclut l’id de la tâche, le status terminal et les champs de résultat spécifiques au point de terminaison. Conservez le résultat dont vous avez besoin et arrêtez l’interrogation. Consultez la référence API du point de terminaison pour connaître la forme exacte du résultat plutôt que de supposer que chaque point de terminaison multimédia renvoie les mêmes champs.

Une réponse failed inclut l’id de la tâche, le status terminal et un error fourni par RunAPI lorsqu’il est disponible. Arrêtez l’interrogation, enregistrez l’identifiant et l’erreur, et ne réessayez que lorsque votre application a classifié l’échec comme transitoire. Une nouvelle tentative crée un nouvel identifiant de tâche.

Ajoutez un callback_url HTTPS public à la requête de création lorsque vous souhaitez que RunAPI envoie les événements de rappel documentés pour ce point de terminaison :

Chaque corps de rappel correspond à un événement de cycle de vie dans la référence API du point de terminaison et omet les détails de facturation liés à l’interrogation. Les rappels terminaux incluent les mêmes champs de résultat que les réponses d’interrogation terminales ; certains points de terminaison envoient également des rappels processing documentés. Renvoyez rapidement une réponse HTTP réussie et gardez l’interrogation disponible pour la réconciliation en cas de retard de livraison ou d’indisponibilité de votre gestionnaire de rappels.

Lisez Callbacks pour créer un secret de callback, vérifier les signatures et gérer les nouvelles tentatives en toute sécurité.