Anleitungen

Schnellstart

Erstellen Sie einen asynchronen Task und verwalten Sie Polling, Abschluss, Fehler und Callbacks.

RunAPI verwendet Tasks für die asynchrone Bild-, Video-, Audio- und Musikgenerierung. Eine Erstellungsanfrage wird schnell zurückgegeben; Ihre Anwendung fragt dann den Task ab oder empfängt die Callback-Ereignisse, die in der API-Referenz des jeweiligen Endpunkts aufgeführt sind.

Einen Task erstellen

Wählen Sie ein Modell und einen Endpunkt im Catalog, senden Sie dann die erforderlichen Eingaben des Endpunkts. Dieses Beispiel startet einen Flux 2 Text-to-Image-Task:

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"
  }'

Eine akzeptierte asynchrone Anfrage gibt 202 Accepted mit einem Task-Bezeichner zurück:

JSON

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

Speichern Sie id zusammen mit Ihrem Anwendungsdatensatz. Es ist der stabile Bezeichner für Polling, Support und Callback-Abgleich.

Doppelte Task-Erstellung verhindern

Task-Erstellungsendpunkte akzeptieren einen optionalen Idempotency-Key-Header mit einem undurchsichtigen Wert von bis zu 512 Zeichen. Generieren Sie einen Wert für jede logische Task und behalten Sie ihn bei der Anfrage, bis Sie wissen, ob sie akzeptiert wurde.

Wenn ein Timeout oder ein Verbindungsfehler das Ergebnis unbekannt lässt, wiederholen Sie dieselbe Task-Erstellungsanfrage mit demselben Schlüssel. RunAPI gibt den ursprünglichen Task zurück, anstatt einen zweiten zu erstellen und dafür zu berechnen. Die Wiederverwendung eines Schlüssels mit einer anderen Task-Erstellungsanfrage gibt 409 Conflict zurück. Generieren Sie einen neuen Schlüssel für einen absichtlich neuen Task und verwenden Sie X-Client-Request-Id nicht als diesen Schlüssel.

Eine unterbrochene synchrone Anfrage wiederherstellen

Langsame synchrone Endpunkte halten die Verbindung in der Regel offen und geben dieselbe terminale Antwort wie zuvor zurück. Für bestehende Integrationen sind keine Polling-Änderungen erforderlich.

Für ein absichtlich kürzeres Verbindungsbudget senden Sie Prefer: wait=N. Wenn der Task nach diesem expliziten Budget noch läuft, gibt RunAPI 202 Accepted mit derselben Task-id, einer undurchsichtigen Location-URL zur Wiederherstellung und Retry-After für die empfohlene Abfrageverzögerung zurück. Folgen Sie Location exakt, anstatt eine Ergebnis-URL zu konstruieren. Ein abgeschlossenes Task-Ergebnis bewahrt den abschließenden HTTP-Status, erlaubte Header, den Inhaltstyp und den Body; dekodieren Sie response.body gemäß response.content_type, was nicht immer JSON ist.

Einen Task abfragen

Hängen Sie den Task-Bezeichner an denselben Endpunktpfad an:

SHELL

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

Fortfahren, solange status den Wert processing hat. Verwenden Sie begrenztes Backoff zwischen Anfragen statt kontinuierlichem Polling. Ein Task wird terminal, wenn sein Status completed oder failed ist.

Vervollständigung verarbeiten

Eine completed-Antwort enthält die Task-id, den terminalen status und die endpunktspezifischen Ergebnisfelder. Speichern Sie das benötigte Ergebnis und beenden Sie das Polling. Entnehmen Sie die genaue Ergebnisstruktur der API-Referenz des Endpunkts, anstatt davon auszugehen, dass jeder Medienendpunkt dieselben Felder zurückgibt.

Fehler behandeln

Eine failed-Antwort enthält die Task-id, den terminalen status und einen von RunAPI verfassten error, sofern vorhanden. Beenden Sie das Polling, notieren Sie Bezeichner und Fehler, und wiederholen Sie den Vorgang nur, wenn Ihre Anwendung den Fehler als vorübergehend eingestuft hat. Ein erneuter Versuch erstellt einen neuen Task-Bezeichner.

Einen Callback empfangen

Fügen Sie der Erstellungsanfrage eine öffentliche HTTPS-callback_url hinzu, wenn RunAPI die für diesen Endpunkt dokumentierten Callback-Ereignisse senden soll:

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"
}

Jeder Callback-Body entspricht einem Lebenszyklusereignis in der API-Referenz des Endpunkts und lässt reine Abruf-Abrechnungsdetails weg. Abschließende Callbacks enthalten dieselben Ergebnisfelder wie abschließende Abrufantworten; einige Endpunkte senden auch dokumentierte processing-Callbacks. Geben Sie schnell eine erfolgreiche HTTP-Antwort zurück und halten Sie Polling für den Abgleich bereit, wenn die Zustellung verzögert ist oder Ihr Callback-Handler nicht verfügbar ist.

Lesen Sie Callbacks, um einen Callback-Secret zu erstellen, Signaturen zu verifizieren und Wiederholungsversuche sicher zu behandeln.