> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt > Use this file to discover all available pages before exploring further. # Warteschlange 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: | Endpunkt | Methode | Beschreibung | | ----------------------------------------------------------- | ------- | ----------------------------------------- | | api.sunra.ai/v1/queue/\{modell-id} | POST | Fügt eine Anfrage zur Warteschlange hinzu | | api.sunra.ai/v1/queue/requests/\{request\_id}/status | GET | Ruft den Status einer Anfrage ab | | api.sunra.ai/v1/queue/requests/\{request\_id}/status/stream | GET | Streamt den Status bis zur Fertigstellung | | api.sunra.ai/v1/queue/requests/\{request\_id} | GET | Ruft die Antwort einer Anfrage ab | | api.sunra.ai/v1/queue/requests/\{request\_id}/cancel | PUT | Bricht eine Anfrage ab | Zum Beispiel, um eine Anfrage mit curl zu senden und sie zur Warteschlange hinzuzufügen: ```bash theme={null} 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`: ```json theme={null} { "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 ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: | Header | Value | | -------------- | ---------------------- | | `Content-Type` | `application/json` | | `User-Agent` | `Sunra-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: ```json theme={null} { "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: ```json theme={null} { "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" } ``` | Feld | Beschreibung | | ---------------- | ----------------------------------------------------------------------------------------------------- | | `id` | Die beim Submit zurückgegebene `request_id`. Verwenden Sie sie zur Deduplizierung von Wiederholungen. | | `object` | Immer `"prediction"`. | | `model` | Modellbesitzer und -name (z. B. `black-forest-labs/flux-1.1-pro`). | | `model_endpoint` | Endpunkt-Slug (z. B. `text-to-image`). | | `status` | `"succeeded"` oder `"failed"`. | | `input` | Der ursprüngliche Anfragekörper, den Sie gesendet haben. | | `output` | Bei `succeeded` vorhanden. Derselbe Antwortkörper, den der Result-Endpunkt zurückgibt. | | `error` | Bei `failed` vorhanden. Ein Objekt, das den Fehler beschreibt; die Struktur hängt vom Fehlertyp ab. | | `created_at` | ISO 8601-Zeitstempel der Anfrageerstellung. | | `completed_at` | ISO 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: ```bash theme={null} 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: ```bash theme={null} 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: | Endpunkttyp | Ratenbegrenzung | Burst-Limit | | :------------------------------- | :------------------- | :-------------------- | | **Zur Warteschlange hinzufügen** | 10 Anfragen/Sekunde | 100 Anfragen/Minute | | **Alle anderen Endpunkte** | 100 Anfragen/Sekunde | 1.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.