Polling e webhook PiAPI: gestire il completamento in modo affidabile

Una richiesta di immagine o video accettata richiede ancora un flusso di completamento. Per le attività dell’API unificata PiAPI, salva l’ID, osserva lo stato finale e gestisci l’output del modello. Il polling è pratico per iniziare; i webhook consentono al backend di reagire alla conclusione.

1. Salvare l’ID e limitare il polling

Dopo la creazione, conserva data.task_id insieme all’ID del tuo lavoro. Interroga la stessa attività con la chiave API del server. Una risposta HTTP riuscita non dimostra la fine della generazione: controlla data.status.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

Con completed, valida data.output secondo il modello; con failed, registra data.error. Limita i tentativi, aumenta gli intervalli e aggiungi una variazione casuale. Il termine di attesa dell’applicazione è una scelta locale: superarlo non prova il fallimento o l’annullamento dell’attività remota. Conserva l’ID per una verifica successiva.

2. Aggiungere un callback autenticato

Unisci il frammento seguente a un corpo valido di creazione, preservando i campi di configurazione esistenti. Usa un endpoint HTTPS pubblico e un segreto dal deposito sicuro del backend. PiAPI documenta l’invio del segreto nell’header x-webhook-secret: verificalo prima di accettare la notifica.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

Il JSON contiene timestamp e data. Verifica che l’attività appartenga all’applicazione, registra o accoda l’evento in modo persistente e restituisci rapidamente 2xx. Esegui download e operazioni lente fuori dal gestore HTTP. Prevedi duplicati: la documentazione descrive nuovi tentativi senza una risposta di successo.

3. Riunire polling e callback

Usa un unico gestore di completamento. Un vincolo persistente di unicità su ID e azione finale evita notifiche doppie o due lavori successivi. Un timestamp da solo non identifica eventi di attività diverse. Ignora aggiornamenti obsoleti dopo uno stato finale e rendi il worker ripetibile in sicurezza dopo un arresto.

Se manca il callback o lo stato è incerto, rileggi l’ID salvato. Un timeout della lettura non giustifica la creazione alla cieca di un’altra attività a pagamento. Distingui errori di trasporto da un fallimento confermato e verifica prima di decidere un nuovo invio.

4. Verificare i casi di errore

Prima del rilascio, ripeti un callback, invia un segreto errato, ritarda la consegna e simula il riavvio del worker. Ogni attività completata deve produrre un solo risultato persistente; ogni fallimento deve conservare l’errore. Segui poi la guida al salvataggio degli output.

Riferimenti: schema API unificato, esempio di lettura attività e documentazione webhook. Gli esempi spiegano l’integrazione e non sono benchmark di generazione reale.