# Aufträge und begrenzte Wartezeit

Fragen Sie Status, Credits und Ergebnisse ab und warten Sie ohne wiederholte Abfragen auf einen Auftrag.

Quelle: https://scifig.ai/de/docs/api/jobs

## Auftrag abfragen

`GET /jobs/{id}` mit Berechtigungsbereich `figures:read` gibt dasselbe Auftragsobjekt wie die Erstellungsanfrage zurück. Aufträge anderer Konten und unbekannte IDs führen beide zu `404 NOT_FOUND`. `GET /jobs?limit=10&cursor=…` listet Ihre Aufträge auf, neueste zuerst; 1–20 pro Seite, folgen Sie `next_cursor`.

```json
{
  "id": "5f4a9a5e-fc45-4eae-9f9c-56b5f686cba5",
  "kind": "chart",
  "status": "succeeded",
  "created_at": "2026-10-14T11:20:05.000Z",
  "credits": { "reserved": 50, "charged": 50, "refunded": 0 },
  "outputs": [
    {
      "file_id": "0b7c…",
      "format": "png",
      "width": 2126,
      "height": 1417,
      "download_url": "https://scifig.ai/api/v1/files/0b7c…?exp=…&sig=…",
      "expires_at": "2026-10-14T12:21:40.000Z",
      "editor_url": "https://scifig.ai/app/datachart?conversation=…"
    }
  ],
  "error": null
}
```

`kind` ist `image_generation`, `image_edit`, `image_upscale`, `image_conversion`, `chart` oder `flowchart`. Antworten enthalten niemals Ihre Beschreibung, Eingaben oder interne Kennungen.

| Ergebnisfeld | Vorhanden | Bedeutung |
| --- | --- | --- |
| file_id | always | An einen anderen Endpunkt oder an `GET /files/{file_id}` übergeben |
| format | always | Dateiendung des Ergebnisses, etwa `png`, `svg` oder `pdf` |
| width, height | PNG-Ergebnisse | Pixelgröße |
| download_url, expires_at | always | Signierter Link, eine Stunde gültig |
| editor_url | Diagramm- und Flussdiagrammaufträge | Öffnet das Ergebnis in seinem Arbeitsbereich auf der Website; Illustrationen und Konvertierungen haben keinen solchen Link |

## Statusverlauf

| status | Bedeutung |
| --- | --- |
| queued | Angenommen; wartet auf verfügbare Kapazität |
| processing | Wird ausgeführt |
| succeeded | Abgeschlossen; `outputs` sind bereit und Credits abgerechnet |
| failed | Kein Ergebnis erstellt; `error.code` nennt den Grund und die Reservierung wird erstattet |
| canceled | Vor Abschluss gestoppt; Credits erstattet |

| `error.code` eines fehlgeschlagenen Auftrags | Bedeutung | Vorgehen |
| --- | --- | --- |
| TASK_TIMED_OUT | Die Aufgabe hat ihr Zeitlimit überschritten und die Credits wurden erstattet. Eine Illustrationsgenerierung oder -bearbeitung kann `late_delivery_until` enthalten: Bis dahin kann das Ergebnis noch kostenlos eintreffen. | Fragen Sie den Auftrag bis `late_delivery_until` weiter ab; senden Sie andernfalls eine neue Anfrage mit einem neuen Schlüssel |
| CONTENT_REJECTED | Die Inhaltsrichtlinie hat das Ergebnis während der Ausführung abgelehnt; die Credits wurden erstattet. Derselbe Code wird als `422` zurückgegeben, wenn die Anfrage selbst bei der Erstellung abgelehnt wird. | Ändern Sie die Beschreibung oder Eingabe und verwenden Sie einen neuen Schlüssel |
| ADMISSION_INCOMPLETE | Der Auftrag wurde nie gestartet, da ein wiederholbarer Fehler ihn verhindert hat. Es wurden keine Credits verbraucht. | Senden Sie dieselbe Anfrage mit demselben Idempotency-Key |
| TASK_NOT_FOUND | Der Auftrag wurde angenommen, aber seine Aufgabe ist nicht mehr auffindbar. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |
| TASK_FAILED | Die Aufgabe ist fehlgeschlagen und die Credits wurden erstattet. Jeder Engine-Fehler ohne eigenen öffentlichen Code wird zu `TASK_FAILED`; der Engine-Code steht in `details.reason`. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |
| INTERNAL_ERROR | Die Aufgabe ist ohne Angabe eines Grundes fehlgeschlagen; die Credits wurden erstattet. | Senden Sie eine neue Anfrage mit einem neuen Schlüssel |

`succeeded`, `failed` und `canceled` sind endgültig, mit einer Ausnahme: Eine Illustrationsgenerierung oder -bearbeitung, die mit `TASK_TIMED_OUT` fehlgeschlagen ist, enthält `late_delivery_until`. Bis dahin kann das Ergebnis noch kostenlos eintreffen und der Auftrag auf `succeeded` wechseln. Fragen Sie ihn weiter ab, statt einen neuen zu erstellen.

Wenn ein Auftrag in der Liste nicht gelesen werden kann, gibt `GET /jobs` `503 SERVICE_UNAVAILABLE` mit `Retry-After: 3` zurück. Wiederholen Sie die Listenanfrage. Der Auftrag wird nicht durch ein fehlgeschlagenes Ergebnis ersetzt.

## Begrenzte Wartezeit

- `Prefer: wait=N` mit 1–30 bei einer Erstellungsanfrage hält die Antwort zurück, bis der Auftrag endgültig ist oder N Sekunden vergangen sind. Endgültige Aufträge geben `200` zurück; noch laufende `202` mit `Location: /api/v1/jobs/{id}` und `Retry-After`.
- Das Warten ändert den Auftrag nicht: `202` ist kein Fehler und der Auftrag läuft nach der Antwort weiter.
- Fragen Sie `GET /jobs/{id}` nicht häufiger als nach `Retry-After`, also 3 Sekunden, ab. Illustrationen dauern gewöhnlich 20–90 Sekunden, Diagramme und Flussdiagramme 30–120 Sekunden.
- Ein fehlgeschlagener Auftrag kann auch eine abgelehnte Anfrage enthalten: Eine mit etwa `402 INSUFFICIENT_CREDITS` oder `422 CONTENT_REJECTED` abgelehnte Erstellungsanfrage bleibt in `GET /jobs` als Auftrag mit Status `failed`, diesem Code und ohne Credits erhalten.
- Serverintegrationen sollten die Auftrags-ID vor dem Warten speichern, damit ein Verbindungsabbruch nie zu einem zweiten Auftrag führt.

## cURL

```bash
curl https://scifig.ai/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer $SCIFIG_API_KEY"
```

## JavaScript

```javascript
const response = await fetch('https://scifig.ai/api/v1/jobs/<job_id>', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.get(
    "https://scifig.ai/api/v1/jobs/<job_id>",
    headers=headers,
    timeout=60,
)
print(response.status_code, response.json())
```