Pour les requêtes qui prennent plus de quelques secondes, typiques dans les applications d’IA, nous avons développé un système de file d’attente. Ce système vous offre un contrôle précis pour gérer les pics de trafic, annuler les requêtes si nécessaire et surveiller l’état de votre requête dans la file d’attente. Il élimine également le besoin de gérer les requêtes HTTP de longue durée.

​
Points de terminaison de la file d’attente

Vous pouvez accéder à toutes les fonctionnalités de la file d’attente via les points de terminaison suivants :
Point de terminaisonMéthodeDescription
api.sunra.ai/v1/queue/{model-id}POSTAjoute une requête à la file d’attente
api.sunra.ai/v1/queue/requests/{request_id}/statusGETRécupère l’état d’une requête
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETDiffuse l’état jusqu’à la fin
api.sunra.ai/v1/queue/requests/{request_id}GETRécupère la réponse d’une requête
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTAnnule une requête
Par exemple, pour soumettre une requête en utilisant curl et l’ajouter à la file d’attente : 
curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Une ville balnéaire inspirée du Studio Ghibli avec des maisons colorées, du linge qui sèche au vent et des chats qui dorment sur les rebords de fenêtre."}'
Voici un exemple de réponse incluant le request_id : 
{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}
La charge utile inclut le request_id et fournit des URL pour vérifier l’état, annuler ou récupérer la réponse, rationalisant votre flux de travail sans développement de point de terminaison supplémentaire.

​
État de la requête

Pour suivre la progression de votre requête, utilisez le point de terminaison fourni avec votre ID de requête unique. Cela vous permet de suivre l’état, la position dans la file d’attente ou de récupérer la réponse une fois qu’elle est prête.

​
Utilisation du point de terminaison

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
Exemple de réponse

Lorsque votre requête est dans la file d’attente, vous recevrez une réponse comme celle-ci : 
{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

​
Statuts possibles

Votre requête peut être dans l’un des trois états suivants :
  • IN_QUEUE : Indique que la requête est en attente de traitement.
    • queue_position : Affiche votre place dans la file d’attente.
    • response_url : URL pour récupérer la réponse une fois le traitement terminé.
  • IN_PROGRESS : La requête est en cours de traitement.
    • logs : Journaux détaillés (si activés) montrant les étapes de traitement.
    • response_url : Où la réponse finale sera disponible.
  • COMPLETED : Le traitement est terminé.
    • logs : Journaux détaillant l’ensemble du processus.
    • response_url : Lien direct vers votre réponse terminée.

​
Activation des journaux

Les journaux fournissent des informations sur le traitement des requêtes. Ils sont désactivés par défaut mais peuvent être activés avec un paramètre de requête : 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Chaque entrée de journal comprend :
  • message : Description de l’événement.
  • level : Gravité (par exemple, INFO, ERROR).
  • source : Origine du journal.
  • timestamp : Heure à laquelle le journal a été généré.

​
Surveillance en temps réel

Pour des mises à jour continues, utilisez le point de terminaison de streaming : 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Cela fournit des mises à jour de l’état en temps réel au format text/event-stream jusqu’à ce que la requête soit terminée.

​
Annulation des requêtes

Si votre requête est toujours en file d’attente, vous pouvez l’annuler avec : 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Récupération des réponses

Une fois votre requête COMPLETED, récupérez la réponse en utilisant : 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Ce point de terminaison fournit également des journaux pour examen.

​
Intégration simplifiée avec le client Sunra

Le client Sunra automatise le suivi de l’état, simplifiant le développement d’applications avec les fonctions Sunra.

​
Limites de taux

Pour garantir une utilisation équitable et la stabilité du système, nos points de terminaison API sont soumis aux limites de taux suivantes :
Type de point de terminaisonLimite de tauxLimite de rafale
Soumettre à la file d’attente10 requêtes/seconde100 requêtes/minute
Tous les autres points de terminaison100 requêtes/seconde1 800 requêtes/minute
Si vous dépassez ces limites, vous recevrez une réponse 403 Forbidden. Nous vous recommandons de mettre en œuvre un mécanisme de nouvelle tentative avec un backoff exponentiel pour gérer ces cas.