Vai al contenuto principale
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.port.moda/v1/queue/{id-modello}POSTAggiunge una richiesta alla coda
api.port.moda/v1/queue/requests/{id-richiesta}/statusGETRecupera lo stato di una richiesta
api.port.moda/v1/queue/requests/{id-richiesta}/status/streamGETTrasmette lo stato in streaming fino al completamento
api.port.moda/v1/queue/requests/{id-richiesta}GETRecupera la risposta di una richiesta
api.port.moda/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.port.moda/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $PORT_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.port.moda/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.port.moda/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.port.moda/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.port.moda/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.port.moda/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.port.moda/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.port.moda/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.port.moda/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.port.moda/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.port.moda/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.port.moda/v1/queue/requests/{request_id}
Questo endpoint fornisce anche i log per la revisione.

​
Integrazione semplificata con il client Port

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

​
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.