File d'attente

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 terminaison	Méthode	Description
api.sunra.ai/v1/queue/{model-id}	POST	Ajoute une requête à la file d’attente
api.sunra.ai/v1/queue/requests/{request_id}/status	GET	Récupère l’état d’une requête
api.sunra.ai/v1/queue/requests/{request_id}/status/stream	GET	Diffuse l’état jusqu’à la fin
api.sunra.ai/v1/queue/requests/{request_id}	GET	Récupère la réponse d’une requête
api.sunra.ai/v1/queue/requests/{request_id}/cancel	PUT	Annule 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.

Webhooks

Si vous préférez être notifié plutôt que de faire du polling, passez un paramètre de requête webhook lors de la soumission. Sunra enverra une requête POST avec le résultat final à cette URL une fois que la requête atteint un état terminal — pas besoin de garder une connexion ouverte ni de planifier du polling.

Activer les Webhooks

Ajoutez un paramètre de requête webhook encodé en URL au point de terminaison de soumission :

curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -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."}'

Encodez l’URL du webhook (par ex. https%3A%2F%2F...) et assurez-vous qu’elle est accessible depuis Sunra ; HTTPS est fortement recommandé. La réponse de soumission est inchangée — vous recevez toujours un request_id ainsi que les mêmes URL de statut/annulation/réponse.

Quand le webhook est déclenché

Sunra appelle votre webhook uniquement lors d’événements terminaux :

succeeded — la requête est terminée et la sortie est incluse dans la charge utile.
failed — la requête a échoué et les détails de l’erreur sont inclus dans la charge utile.

Les états intermédiaires (IN_QUEUE, IN_PROGRESS) ne déclenchent pas de webhook. Si vous avez aussi besoin de mises à jour de progression, combinez le webhook avec les points de terminaison streaming ou polling décrits ci-dessus.

Format de la requête

Sunra envoie une requête POST à votre URL de webhook avec :

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Sunra-AI-Webhook/1.0`

Votre point de terminaison doit répondre avec un code 2xx en moins de 5 secondes. Acquittez rapidement et déléguez tout traitement lourd à une tâche d’arrière-plan — les réponses lentes sont traitées comme des échecs et déclenchent des tentatives.

Charge utile

Un événement de succès :

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Une ville balnéaire inspirée du Studio Ghibli..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Un événement d’échec remplace output par error. Le contenu exact d’error varie selon le type d’échec — l’exemple ci-dessous montre une forme courante :

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Une ville balnéaire inspirée du Studio Ghibli..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Message d'erreur lisible"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Champ	Description
`id`	Le `request_id` retourné lors de la soumission. Utilisez-le pour dédupliquer les tentatives.
`object`	Toujours `"prediction"`.
`model`	Le propriétaire et le nom du modèle (par ex. `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	Le slug du point de terminaison (par ex. `text-to-image`).
`status`	`"succeeded"` ou `"failed"`.
`input`	Le corps de la requête originale que vous avez soumise.
`output`	Présent en cas de `succeeded`. Le même corps de réponse retourné par le point de terminaison de résultat.
`error`	Présent en cas de `failed`. Un objet décrivant l’échec ; sa structure dépend du type d’échec.
`created_at`	Horodatage ISO 8601 de la création de la requête.
`completed_at`	Horodatage ISO 8601 du moment où la requête a atteint l’état terminal.

Comportement de relance

La livraison du webhook est de type au-moins-une-fois. Si votre point de terminaison expire (5 s) ou retourne un statut non-2xx, Sunra réessaye avec un backoff exponentiel — jusqu’à 3 tentatives avec des délais débutant à 10 secondes et plafonnés à 30 secondes. Après la dernière tentative, l’échec est journalisé et aucune tentative supplémentaire n’est effectuée. Comme les tentatives peuvent livrer le même événement plusieurs fois, votre gestionnaire doit être idempotent — utilisez le champ id comme clé de déduplication.

Bonnes pratiques

Utilisez HTTPS et vérifiez que le trafic atteint bien le point de terminaison attendu.
Répondez 2xx immédiatement et traitez la charge utile de manière asynchrone.
Considérez la livraison comme au-moins-une-fois et dédupliquez par id.
Combinez les webhooks avec les points de terminaison de polling ou streaming si vous avez besoin de mises à jour de progression avant l’événement terminal.

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 terminaison	Limite de taux	Limite de rafale
Soumettre à la file d’attente	10 requêtes/seconde	100 requêtes/minute
Tous les autres points de terminaison	100 requêtes/seconde	1 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.

Aperçu

Multimodal

LLM

Bibliothèques clientes

Points de terminaison de la file d’attente

État de la requête

Utilisation du point de terminaison

Exemple de réponse

Statuts possibles

Activation des journaux

Surveillance en temps réel

Webhooks

Activer les Webhooks

Quand le webhook est déclenché

Format de la requête

Charge utile

Comportement de relance

Bonnes pratiques

Annulation des requêtes

Récupération des réponses

Intégration simplifiée avec le client Sunra

Limites de taux

Aperçu

Multimodal

LLM

Bibliothèques clientes

Documentation Index

​Points de terminaison de la file d’attente

​État de la requête

​Utilisation du point de terminaison

​Exemple de réponse

​Statuts possibles

​Activation des journaux

​Surveillance en temps réel

​Webhooks

​Activer les Webhooks

​Quand le webhook est déclenché

​Format de la requête

​Charge utile

​Comportement de relance

​Bonnes pratiques

​Annulation des requêtes

​Récupération des réponses

​Intégration simplifiée avec le client Sunra

​Limites de taux

Points de terminaison de la file d’attente

État de la requête

Utilisation du point de terminaison

Exemple de réponse

Statuts possibles

Activation des journaux

Surveillance en temps réel

Webhooks

Activer les Webhooks

Quand le webhook est déclenché

Format de la requête

Charge utile

Comportement de relance

Bonnes pratiques

Annulation des requêtes

Récupération des réponses

Intégration simplifiée avec le client Sunra

Limites de taux