SciFig
Kostenlos starten

API-Referenz

Aufträge und begrenzte Wartezeit

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

Als Markdown anzeigen

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.

{
  "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.

ErgebnisfeldVorhandenBedeutung
file_idalwaysAn einen anderen Endpunkt oder an GET /files/{file_id} übergeben
formatalwaysDateiendung des Ergebnisses, etwa png, svg oder pdf
width, heightPNG-ErgebnissePixelgröße
download_url, expires_atalwaysSignierter Link, eine Stunde gültig
editor_urlDiagramm- und FlussdiagrammaufträgeÖffnet das Ergebnis in seinem Arbeitsbereich auf der Website; Illustrationen und Konvertierungen haben keinen solchen Link

Statusverlauf#

statusBedeutung
queuedAngenommen; wartet auf verfügbare Kapazität
processingWird ausgeführt
succeededAbgeschlossen; outputs sind bereit und Credits abgerechnet
failedKein Ergebnis erstellt; error.code nennt den Grund und die Reservierung wird erstattet
canceledVor Abschluss gestoppt; Credits erstattet
`error.code` eines fehlgeschlagenen AuftragsBedeutungVorgehen
TASK_TIMED_OUTDie 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_REJECTEDDie 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_INCOMPLETEDer 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_FOUNDDer Auftrag wurde angenommen, aber seine Aufgabe ist nicht mehr auffindbar.Senden Sie eine neue Anfrage mit einem neuen Schlüssel
TASK_FAILEDDie 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_ERRORDie 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#

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

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#

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())
ZurückFlussdiagramme erstellen und bearbeitenWeiterCreditsDie API verwendet Ihre SciFig-Credits: ein Guthaben für Website, API und MCP.