Per le richieste che richiedono più di qualche secondo, tipiche nelle applicazioni di intelligenza artificiale, abbiamo sviluppato un sistema di code. Questo sistema ti offre un controllo granulare per gestire i picchi di traffico, annullare le richieste se necessario e monitorare lo stato della tua richiesta in coda. Elimina anche la necessità di gestire richieste HTTP a lunga esecuzione.

​
Endpoint della coda

Puoi accedere a tutte le funzionalità della coda tramite i seguenti endpoint:
EndpointMetodoDescrizione
api.sunra.ai/v1/queue/{id-modello}POSTAggiunge una richiesta alla coda
api.sunra.ai/v1/queue/requests/{id-richiesta}/statusGETRecupera lo stato di una richiesta
api.sunra.ai/v1/queue/requests/{id-richiesta}/status/streamGETTrasmette lo stato in streaming fino al completamento
api.sunra.ai/v1/queue/requests/{id-richiesta}GETRecupera la risposta di una richiesta
api.sunra.ai/v1/queue/requests/{id-richiesta}/cancelPUTAnnulla una richiesta
Ad esempio, per inviare una richiesta utilizzando curl e aggiungerla alla coda: 
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": "Una città di mare ispirata allo Studio Ghibli con case colorate, panni stesi e gatti che dormono sui davanzali."}'
Ecco una risposta di esempio che include il 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"
}
Il payload include il request_id e fornisce URL per controllare lo stato, annullare o recuperare la risposta, semplificando il flusso di lavoro senza ulteriore sviluppo di endpoint.

​
Stato della richiesta

Per monitorare l’avanzamento della tua richiesta, utilizza l’endpoint fornito con il tuo ID richiesta univoco. Ciò ti consente di tenere traccia dello stato, della posizione in coda o di recuperare la risposta una volta pronta.

​
Utilizzo dell’endpoint

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

​
Risposta di esempio

Quando la tua richiesta è in coda, riceverai una risposta come questa: 
{
  "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"
}

​
Stati possibili

La tua richiesta può trovarsi in uno dei tre stati seguenti:
  • IN_QUEUE: indica che la richiesta è in attesa di essere elaborata.
    • queue_position: mostra la tua posizione nella coda.
    • response_url: URL per recuperare la risposta una volta completata l’elaborazione.
  • IN_PROGRESS: la richiesta è attualmente in fase di elaborazione.
    • logs: log dettagliati (se abilitati) che mostrano i passaggi di elaborazione.
    • response_url: dove sarà disponibile la risposta finale.
  • COMPLETED: l’elaborazione è terminata.
    • logs: log che descrivono in dettaglio l’intero processo.
    • response_url: link diretto alla tua risposta completata.

​
Abilitazione dei log

I log forniscono informazioni dettagliate sull’elaborazione delle richieste. Sono disabilitati per impostazione predefinita ma possono essere abilitati con un parametro di query: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Ogni voce di log include:
  • message: descrizione dell’evento.
  • level: gravità (ad esempio, INFO, ERROR).
  • source: origine del log.
  • timestamp: ora in cui è stato generato il log.

​
Monitoraggio in tempo reale

Per aggiornamenti continui, utilizza l’endpoint di streaming: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Ciò fornisce aggiornamenti di stato in tempo reale in formato text/event-stream fino al completamento della richiesta.

​
Annullamento delle richieste

Se la tua richiesta è ancora in coda, puoi annullarla con: 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Recupero delle risposte

Una volta che la tua richiesta è COMPLETED, recupera la risposta utilizzando: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Questo endpoint fornisce anche i log per la revisione.

​
Integrazione semplificata con il client Sunra

Il client Sunra automatizza il monitoraggio dello stato, semplificando lo sviluppo di app con le funzioni Sunra.

​
Limiti di velocità

Per garantire un utilizzo equo e la stabilità del sistema, i nostri endpoint API sono soggetti ai seguenti limiti di velocità:
Tipo di endpointLimite di velocitàLimite di burst
Invia alla coda10 richieste/secondo100 richieste/minuto
Tutti gli altri endpoint100 richieste/secondo1.800 richieste/minuto
Se si superano questi limiti, si riceverà una risposta 403 Forbidden. Si consiglia di implementare un meccanismo di tentativi con backoff esponenziale per gestire questi casi.