Coda

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:

Endpoint	Metodo	Descrizione
api.sunra.ai/v1/queue/{id-modello}	POST	Aggiunge una richiesta alla coda
api.sunra.ai/v1/queue/requests/{id-richiesta}/status	GET	Recupera lo stato di una richiesta
api.sunra.ai/v1/queue/requests/{id-richiesta}/status/stream	GET	Trasmette lo stato in streaming fino al completamento
api.sunra.ai/v1/queue/requests/{id-richiesta}	GET	Recupera la risposta di una richiesta
api.sunra.ai/v1/queue/requests/{id-richiesta}/cancel	PUT	Annulla 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.

Webhooks

Se preferisci essere notificato invece di fare polling, passa un parametro di query webhook al momento dell’invio della richiesta. Sunra eseguirà un POST con il risultato finale a quell’URL non appena la richiesta raggiunge uno stato terminale, quindi non è necessario mantenere una connessione aperta o pianificare il polling.

Abilitazione dei Webhooks

Aggiungi un parametro di query webhook codificato come URL all’endpoint di invio:

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": "Una città balneare ispirata allo Studio Ghibli con case colorate, panni stesi al vento e gatti che dormono sui davanzali."}'

Codifica l’URL del webhook come URL (es. https%3A%2F%2F...) e assicurati che Sunra possa raggiungerlo; HTTPS è fortemente consigliato. La risposta di invio rimane invariata — ricevi sempre un request_id e gli stessi URL di status/cancel/response.

Quando viene attivato il Webhook

Sunra chiama il tuo webhook solo per eventi terminali:

succeeded — la richiesta è stata completata e l’output è incluso nel payload.
failed — la richiesta è fallita e i dettagli dell’errore sono inclusi nel payload.

Gli stati intermedi (IN_QUEUE, IN_PROGRESS) non attivano un webhook. Se hai bisogno anche di aggiornamenti di avanzamento, combina il webhook con gli endpoint di streaming o polling descritti sopra.

Formato della Richiesta

Sunra invia una richiesta POST al tuo URL webhook con:

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

Il tuo endpoint deve rispondere con un codice di stato 2xx entro 5 secondi. Conferma rapidamente e delega il lavoro pesante a un job in background — risposte lente vengono trattate come fallimenti e attivano i tentativi.

Payload

Un evento di successo:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Una città balneare ispirata allo Studio Ghibli..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Un evento di fallimento sostituisce output con error. Il contenuto esatto di error varia a seconda del tipo di fallimento — l’esempio seguente mostra una forma comune:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Una città balneare ispirata allo Studio Ghibli..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Messaggio di errore leggibile"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Campo	Descrizione
`id`	Il `request_id` restituito al momento dell’invio. Usalo per deduplicare i tentativi.
`object`	Sempre `"prediction"`.
`model`	Proprietario e nome del modello (es. `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	Slug dell’endpoint (es. `text-to-image`).
`status`	`"succeeded"` o `"failed"`.
`input`	Il corpo della richiesta originale che hai inviato.
`output`	Presente in caso di `succeeded`. Lo stesso corpo di risposta restituito dall’endpoint dei risultati.
`error`	Presente in caso di `failed`. Un oggetto che descrive il fallimento; la struttura dipende dal tipo di fallimento.
`created_at`	Timestamp ISO 8601 di creazione della richiesta.
`completed_at`	Timestamp ISO 8601 di quando la richiesta ha raggiunto lo stato terminale.

Comportamento dei Tentativi

La consegna del webhook è almeno-una-volta. Se il tuo endpoint va in timeout (5 s) o restituisce uno stato non-2xx, Sunra riprova con backoff esponenziale — fino a 3 tentativi con ritardi a partire da 10 secondi e limitati a 30 secondi. Dopo l’ultimo tentativo, il fallimento viene registrato e non vengono effettuati ulteriori tentativi. Poiché i tentativi possono consegnare lo stesso evento più di una volta, il tuo handler dovrebbe essere idempotente — usa il campo id come chiave di deduplicazione.

Best Practice

Usa HTTPS e verifica che il traffico raggiunga l’endpoint atteso.
Rispondi 2xx immediatamente e processa il payload in modo asincrono.
Considera la consegna come almeno-una-volta e deduplica per id.
Combina i webhook con gli endpoint di polling o streaming se hai bisogno di aggiornamenti di avanzamento prima dell’evento terminale.

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 endpoint	Limite di velocità	Limite di burst
Invia alla coda	10 richieste/secondo	100 richieste/minuto
Tutti gli altri endpoint	100 richieste/secondo	1.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.

Panoramica

Multimodal

LLM

Librerie client

Endpoint della coda

Stato della richiesta

Utilizzo dell’endpoint

Risposta di esempio

Stati possibili

Abilitazione dei log

Monitoraggio in tempo reale

Webhooks

Abilitazione dei Webhooks

Quando viene attivato il Webhook

Formato della Richiesta

Payload

Comportamento dei Tentativi

Best Practice

Annullamento delle richieste

Recupero delle risposte

Integrazione semplificata con il client Sunra

Limiti di velocità

​Endpoint della coda

​Stato della richiesta

​Utilizzo dell’endpoint

​Risposta di esempio

​Stati possibili

​Abilitazione dei log

​Monitoraggio in tempo reale

​Webhooks

​Abilitazione dei Webhooks

​Quando viene attivato il Webhook

​Formato della Richiesta

​Payload

​Comportamento dei Tentativi

​Best Practice

​Annullamento delle richieste

​Recupero delle risposte

​Integrazione semplificata con il client Sunra

​Limiti di velocità

Endpoint della coda

Stato della richiesta

Utilizzo dell’endpoint

Risposta di esempio

Stati possibili

Abilitazione dei log

Monitoraggio in tempo reale

Webhooks

Abilitazione dei Webhooks

Quando viene attivato il Webhook

Formato della Richiesta

Payload

Comportamento dei Tentativi

Best Practice

Annullamento delle richieste

Recupero delle risposte

Integrazione semplificata con il client Sunra

Limiti di velocità