Guide

Guida introduttiva

Crea un Task asincrono e gestisci polling, completamento, errori e callback.

RunAPI utilizza i Task per la generazione asincrona di immagini, video, audio e musica. Una richiesta di creazione risponde rapidamente; l’applicazione effettua poi polling del Task o riceve gli eventi callback elencati nel Riferimento API dell’endpoint corrispondente.

Creare un Task

Scegli un modello e un endpoint nel Catalogo, quindi invia gli input richiesti dall’endpoint. Questo esempio avvia un Task Flux 2 da testo a immagine:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

Una richiesta asincrona accettata restituisce 202 Accepted con un identificatore di Task:

JSON

{
  "id": "task_id",
  "status": "processing"
}

Conserva id con il record della tua applicazione. È l’identificatore stabile utilizzato per il polling, il supporto e la riconciliazione dei callback.

Prevenire la creazione di Task duplicati

Gli endpoint di creazione delle attività accettano un header facoltativo Idempotency-Key con un valore opaco fino a 512 caratteri. Genera un valore per ogni attività logica e conservalo con la richiesta fino a quando non sai se è stata accettata.

Se un timeout o un errore di connessione lascia il risultato sconosciuto, riprova la stessa identica richiesta di creazione del Task con la stessa chiave. RunAPI restituisce il Task originale invece di crearne e addebitarne uno nuovo. Il riutilizzo di una chiave con una richiesta di creazione di Task diversa restituisce 409 Conflict. Genera una nuova chiave per un Task intenzionalmente nuovo e non utilizzare X-Client-Request-Id come questa chiave.

Recuperare una richiesta sincrona interrotta

Gli endpoint sincroni lenti di norma mantengono la connessione aperta e restituiscono la stessa risposta terminale di prima. Non sono necessarie modifiche al polling per le integrazioni esistenti.

Per un budget di connessione intenzionalmente più breve, invia Prefer: wait=N. Se il Task è ancora in esecuzione dopo quel budget esplicito, RunAPI restituisce 202 Accepted con lo stesso id del Task, un URL Location opaco per il recupero e Retry-After per il ritardo di query suggerito. Segui Location esattamente anziché costruire un URL di risultato. Un risultato Task completato conserva lo stato HTTP terminale, le intestazioni consentite, il tipo di contenuto e il corpo; decodifica response.body in base a response.content_type, che non è sempre JSON.

Esegui il polling di un Task

Aggiungi l’identificatore del Task allo stesso percorso dell’endpoint:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Continua finché status è processing. Usa un backoff limitato tra le richieste invece di eseguire il polling in modo continuo. Un Task diventa terminale quando il suo status è completed o failed.

Gestisci il completamento

Una risposta completed include l’id del Task, lo status terminale e i campi risultato specifici dell’endpoint. Conserva il risultato necessario e interrompi il polling. Consulta il Riferimento API dell’endpoint per la forma esatta del risultato anziché presumere che ogni endpoint multimediale restituisca gli stessi campi.

Gestisci i fallimenti

Una risposta failed include l’id del Task, lo status terminale e un error redatto da RunAPI quando disponibile. Interrompi il polling, registra l’identificatore e l’errore, e riprova solo quando l’applicazione ha classificato il fallimento come transitorio. Un nuovo tentativo crea un nuovo identificatore di Task.

Ricevere un callback

Aggiungi un callback_url HTTPS pubblico alla richiesta di creazione quando vuoi che RunAPI invii gli eventi di callback documentati per quell’endpoint:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Ogni corpo di callback corrisponde a un evento del ciclo di vita nel Riferimento API dell’endpoint e omette i dettagli di fatturazione relativi al solo polling. I callback terminali includono gli stessi campi di risultato delle risposte di polling terminali; alcuni endpoint inviano anche callback processing documentati. Restituisci rapidamente una risposta HTTP di successo e mantieni disponibile il polling per la riconciliazione quando la consegna è ritardata o il tuo gestore di callback non è disponibile.

Leggi Callback per creare un Callback Secret, verificare le firme e gestire i tentativi in modo sicuro.