Zum Hauptinhalt springen
Für Anfragen, die länger als ein paar Sekunden dauern, was bei KI-Anwendungen typisch ist, haben wir ein Warteschlangensystem entwickelt. Dieses System bietet Ihnen eine feingranulare Kontrolle, um Verkehrsspitzen zu bewältigen, Anfragen bei Bedarf abzubrechen und den Status Ihrer Anfrage in der Warteschlange zu überwachen. Es eliminiert auch die Notwendigkeit, lang andauernde HTTP-Anfragen zu behandeln.

​
Warteschlangen-Endpunkte

Sie können auf alle Warteschlangenfunktionen über die folgenden Endpunkte zugreifen:
EndpunktMethodeBeschreibung
api.sunra.ai/v1/queue/{modell-id}POSTFügt eine Anfrage zur Warteschlange hinzu
api.sunra.ai/v1/queue/requests/{request_id}/statusGETRuft den Status einer Anfrage ab
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETStreamt den Status bis zur Fertigstellung
api.sunra.ai/v1/queue/requests/{request_id}GETRuft die Antwort einer Anfrage ab
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTBricht eine Anfrage ab
Zum Beispiel, um eine Anfrage mit curl zu senden und sie zur Warteschlange hinzuzufügen: 
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": "Eine von Studio Ghibli inspirierte Küstenstadt mit bunten Häusern, flatternder Wäsche und auf Fensterbänken schlafenden Katzen."}'
Hier ist eine Beispielantwort einschließlich der 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"
}
Die Nutzlast enthält die request_id und bietet URLs zum Überprüfen des Status, zum Abbrechen oder zum Abrufen der Antwort, was Ihren Arbeitsablauf ohne zusätzliche Endpunktentwicklung optimiert.

​
Anforderungsstatus

Um den Fortschritt Ihrer Anfrage zu überwachen, verwenden Sie den bereitgestellten Endpunkt mit Ihrer eindeutigen Anfrage-ID. Dies ermöglicht es Ihnen, den Status, die Position in der Warteschlange zu verfolgen oder die Antwort abzurufen, sobald sie fertig ist.

​
Endpunktnutzung

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​
Beispielantwort

Wenn sich Ihre Anfrage in der Warteschlange befindet, erhalten Sie eine Antwort wie diese: 
{
  "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"
}

​
Mögliche Status

Ihre Anfrage kann sich in einem von drei Zuständen befinden:
  • IN_QUEUE: Zeigt an, dass die Anfrage auf die Verarbeitung wartet.
    • queue_position: Zeigt Ihren Platz in der Warteschlange an.
    • response_url: URL zum Abrufen der Antwort nach Abschluss der Verarbeitung.
  • IN_PROGRESS: Die Anfrage wird gerade verarbeitet.
    • logs: Detaillierte Protokolle (falls aktiviert), die die Verarbeitungsschritte zeigen.
    • response_url: Wo die endgültige Antwort verfügbar sein wird.
  • COMPLETED: Die Verarbeitung ist abgeschlossen.
    • logs: Protokolle, die den gesamten Prozess detailliert beschreiben.
    • response_url: Direkter Link zu Ihrer abgeschlossenen Antwort.

​
Protokolle aktivieren

Protokolle bieten Einblicke in die Anfrageverarbeitung. Sie sind standardmäßig deaktiviert, können aber mit einem Abfrageparameter aktiviert werden: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1
Jeder Protokolleintrag enthält:
  • message: Beschreibung des Ereignisses.
  • level: Schweregrad (z. B. INFO, ERROR).
  • source: Ursprung des Protokolls.
  • timestamp: Zeitpunkt der Protokollgenerierung.

​
Echtzeitüberwachung

Für kontinuierliche Updates verwenden Sie den Streaming-Endpunkt: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream
Dies bietet Echtzeit-Statusaktualisierungen im text/event-stream-Format, bis die Anfrage abgeschlossen ist.

​
Webhooks

Wenn Sie lieber benachrichtigt werden möchten, anstatt zu pollen, übergeben Sie beim Senden einer Anfrage einen webhook-Query-Parameter. Sunra sendet das Endergebnis per POST an diese URL, sobald die Anfrage einen Endzustand erreicht — Sie müssen also keine Verbindung offen halten oder Polling planen.

​
Webhooks aktivieren

Hängen Sie einen URL-codierten webhook-Query-Parameter an den Submit-Endpunkt an: 
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": "Eine vom Studio Ghibli inspirierte Küstenstadt mit bunten Häusern, im Wind flatternder Wäsche und Katzen, die auf Fensterbänken schlafen."}'
Codieren Sie die Webhook-URL als URL (z. B. https%3A%2F%2F...) und stellen Sie sicher, dass Sunra sie erreichen kann; HTTPS wird dringend empfohlen. Die Submit-Antwort bleibt unverändert — Sie erhalten weiterhin eine request_id sowie die gleichen Status-/Cancel-/Response-URLs.

​
Wann der Webhook ausgelöst wird

Sunra ruft Ihren Webhook nur bei Endereignissen auf:
  • succeeded — Die Anfrage ist abgeschlossen und die Ausgabe ist im Payload enthalten.
  • failed — Die Anfrage ist fehlgeschlagen und Fehlerdetails sind im Payload enthalten.
Zwischenstatus (IN_QUEUE, IN_PROGRESS) lösen keinen Webhook aus. Wenn Sie auch Fortschrittsaktualisierungen benötigen, kombinieren Sie den Webhook mit den oben beschriebenen Streaming- oder Polling-Endpunkten.

​
Anfrageformat

Sunra sendet eine POST-Anfrage an Ihre Webhook-URL mit:
HeaderValue
Content-Typeapplication/json
User-AgentSunra-AI-Webhook/1.0
Ihr Endpunkt muss innerhalb von 5 Sekunden mit einem 2xx-Statuscode antworten. Bestätigen Sie schnell und lagern Sie aufwändige Arbeit in einen Hintergrund-Job aus — langsame Antworten werden als Fehler gewertet und lösen Wiederholungen aus.

​
Payload

Ein Erfolgsereignis: 
{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Eine vom Studio Ghibli inspirierte Küstenstadt..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
Ein Fehlerereignis ersetzt output durch error. Der genaue Inhalt von error hängt vom Fehlertyp ab — das folgende Beispiel zeigt eine gängige Form: 
{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Eine vom Studio Ghibli inspirierte Küstenstadt..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Menschenlesbare Fehlermeldung"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}
FeldBeschreibung
idDie beim Submit zurückgegebene request_id. Verwenden Sie sie zur Deduplizierung von Wiederholungen.
objectImmer "prediction".
modelModellbesitzer und -name (z. B. black-forest-labs/flux-1.1-pro).
model_endpointEndpunkt-Slug (z. B. text-to-image).
status"succeeded" oder "failed".
inputDer ursprüngliche Anfragekörper, den Sie gesendet haben.
outputBei succeeded vorhanden. Derselbe Antwortkörper, den der Result-Endpunkt zurückgibt.
errorBei failed vorhanden. Ein Objekt, das den Fehler beschreibt; die Struktur hängt vom Fehlertyp ab.
created_atISO 8601-Zeitstempel der Anfrageerstellung.
completed_atISO 8601-Zeitstempel, wann die Anfrage den Endzustand erreichte.

​
Wiederholungsverhalten

Die Webhook-Zustellung erfolgt mindestens-einmal. Wenn Ihr Endpunkt das Timeout (5 s) überschreitet oder einen Status zurückgibt, der nicht 2xx ist, versucht Sunra es mit exponentiellem Backoff erneut — bis zu 3 Wiederholungen mit Verzögerungen ab 10 Sekunden, gedeckelt bei 30 Sekunden. Nach der letzten Wiederholung wird der Fehler protokolliert und es werden keine weiteren Versuche unternommen. Da Wiederholungen dasselbe Ereignis mehr als einmal zustellen können, sollte Ihr Handler idempotent sein — verwenden Sie das id-Feld als Deduplizierungsschlüssel.

​
Best Practices

  • Verwenden Sie HTTPS und stellen Sie sicher, dass der Datenverkehr den erwarteten Endpunkt erreicht.
  • Antworten Sie sofort mit 2xx und verarbeiten Sie das Payload asynchron.
  • Behandeln Sie die Zustellung als mindestens-einmal und deduplizieren Sie nach id.
  • Kombinieren Sie Webhooks mit Polling- oder Streaming-Endpunkten, wenn Sie vor dem Endereignis Fortschrittsaktualisierungen benötigen.

​
Anfragen abbrechen

Wenn sich Ihre Anfrage noch in der Warteschlange befindet, können Sie sie mit folgendem Befehl abbrechen: 
curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​
Antworten abrufen

Sobald Ihre Anfrage COMPLETED ist, rufen Sie die Antwort mit folgendem Befehl ab: 
curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}
Dieser Endpunkt bietet auch Protokolle zur Überprüfung.

​
Vereinfachte Integration mit dem Sunra Client

Der Sunra-Client automatisiert die Statusverfolgung und vereinfacht die App-Entwicklung mit Sunra-Funktionen.

​
Ratenbegrenzungen

Um eine faire Nutzung und Systemstabilität zu gewährleisten, unterliegen unsere API-Endpunkte den folgenden Ratenbegrenzungen:
EndpunkttypRatenbegrenzungBurst-Limit
Zur Warteschlange hinzufügen10 Anfragen/Sekunde100 Anfragen/Minute
Alle anderen Endpunkte100 Anfragen/Sekunde1.800 Anfragen/Minute
Wenn Sie diese Grenzen überschreiten, erhalten Sie eine 403 Forbidden-Antwort. Wir empfehlen die Implementierung eines Wiederholungsmechanismus mit exponentiellem Backoff, um diese Fälle zu behandeln.