Docs

Aufträge und Ergebnisse

Zuletzt aktualisiert: 2026-10-034 Min. Lesezeit

Manche Werkzeuge antworten sofort (synchron), andere legen einen Auftrag an und beenden ihn im Hintergrund. Diese Seite behandelt den zweiten Fall: wie Sie erkennen, dass der Auftrag fertig ist, und wie Sie das Ergebnis holen.

Antwort beim Anlegen

Ein asynchrones Werkzeug antwortet mit 202:

{ "jobId": "...", "status": "...", "state": "pending", "requestId": "req_..." }

Das Feld state ist für alle Werkzeuge gleich - richten Sie sich danach:

WertBedeutung
pendingangenommen, noch nicht gestartet
runningläuft
action_requiredwartet auf Sie (Berichtsprüfung: extrahierte Daten bestätigen)
completedfertig
partialteilweise fertig: einige Dateien sind fehlgeschlagen (beim Content-Paket möglich)
failedfehlgeschlagen

status ist der Rohstatus des Werkzeugs (DONE, processing, need_confirm usw.). Er bleibt aus Kompatibilitätsgründen; bauen Sie neue Integrationen auf state.

Auftrags-ID

Jede Auftragsantwort, von jedem Werkzeug, enthält das Feld jobId: beim Anlegen, im Status und nach der Bestätigung. Fragen Sie den Status damit ab.

Vor Version 1.6.0 lieferten die Werkzeuge die ID unter verschiedenen Namen (id, _id, contentGenJobId). Diese Felder bleiben für bestehende Integrationen erhalten, sind aber veraltet: Verwenden Sie jobId.

Abfragen

Der Status liegt unter GET /<Werkzeugpfad>/jobs/{id}:

WerkzeugStatus
Vollständiger BewertungsberichtGET /valuation/report/jobs/{id}
BerichtsprüfungGET /valuation/review/jobs/{id}
Content-PaketGET /content/generate/jobs/{id}
TexteGET /text/generate/jobs/{id}
VideoGET /video/create/jobs/{id}
AvatarGET /avatar/video/jobs/{id}
FotoGET /photo/enhance/jobs/{id}
GrundrissGET /floorplan/create/jobs/{id}
PDFGET /pdf/create/jobs/{id}
  • Abfragen ist kostenlos und zählt nicht als API-Aufruf, fällt aber unter das Ratenlimit. Alle 3-5 Sekunden genügt.
  • Einen Auftrag sieht nur das Konto, dessen Schlüssel ihn angelegt hat. Eine fremde oder unbekannte ID liefert dasselbe 404.
  • Ein Agentenschlüssel einer Agentur sieht nur die Aufträge, die er selbst gestartet hat; der agenturweite Schlüssel sieht alle Aufträge der Agentur.
  • Ein Auftrag lässt sich 7 Tage nach dem Anlegen abfragen. Danach antwortet GET .../jobs/{id} mit 404, und Dateien von Content-Paket, Texten und Video lassen sich nicht mehr über die API herunterladen.
  • Die Statusantwort enthält dieselben status und state sowie das Ergebnis, sobald es vorliegt. Ein fehlgeschlagener Auftrag für Content-Paket, Texte oder Video enthält error, ein Fotoauftrag metadata.error - den Grund als allgemeinen Text.

Grundriss und Berichtsprüfung verarbeiten das Dokument sofort: Die 202-Antwort enthält bereits den Endzustand (completed, failed oder action_required), Abfragen ist optional.

Wenn der Auftrag auf Sie wartet

Die Berichtsprüfung (Bewertung) hält nach dem Lesen des Dokuments im Zustand action_required an und liefert die extrahierten Daten in extracted. Prüfen und bestätigen Sie sie:

curl -X POST https://developers.grem.capital/api/v1/valuation/review/jobs/JOB_ID/confirm \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Ein leerer Body bedeutet «alles korrekt». Um einen Wert zu korrigieren, senden Sie in extracted nur die geänderten Felder unter denselben Namen wie in der Antwort (das verschachtelte Objekt subject wird eine Ebene tief zusammengeführt). Danach wechselt der Auftrag zu running, und das Ergebnis kommt wie gewohnt.

Webhooks statt Abfragen

Jedes asynchrone Werkzeug sendet ein Ereignis <werkzeug>.completed oder <werkzeug>.failed (das Content-Paket zusätzlich content.partial). Abonnieren und Signatur prüfen: Webhooks.

  • Das Ereignis kommt meist innerhalb einer Minute nach Auftragsende.
  • Ein Auftrag wird nur verfolgt, wenn ein Abonnement für sein Ereignis beim Anlegen des Auftrags bereits bestand. Abonnieren Sie vorher, nicht nach dem Start.
  • Ist ein Auftrag nach 30 Minuten nicht fertig, kommt .failed mit reason: "timeout". Der Auftrag selbst kann trotzdem noch fertig werden - der Status lässt sich abfragen.

Fertige Dateien

Dateien laden Sie über GET /artifacts/{path} mit demselben Schlüssel (Bereich tools:artifacts). Kostenlos, mit Range. {path} ist einer dieser Pfade:

WasPfad
Datei des Content-Pakets, der Texte oder des Videosv1/ai/assistant/announcement/jobs/{jobId}/artifacts/{artifactId}/download
Avatar-Videov1/ai/assistant/avatar/jobs/{jobId}/artifacts/{artifactId}/download
PDF-Präsentationv1/ai/pdf-generator/files/{id}/download
Verbessertes Fotov1/ai/photo-enhancement/jobs/{jobId}/download/{variant}
PDF des Bewertungsberichtsv1/ai/appraisal/reports/{id}/pdf
PDF der Mietbewertungv1/ai/appraisal/rent/{id}/pdf
Prüfberichtv1/ai/appraisal/reviews/{id}/report.pdf oder report.docx
Grundrissberichtv1/ai/floor-plan/jobs/{id}/report.pdf
Flyer-Dateiv1/ai/flyer/file/{name}
Videotitel (Vorhören)v1/ai/video-generator/music/{trackId}
Gewöhnliche Dateider Pfad /files/... aus der Werkzeugantwort

Die Datei-IDs des Content-Pakets stehen im Feld artifacts des Auftragsstatus. Dateien von Content-Paket, Texten und Video sind nur für Aufträge verfügbar, die dasselbe Konto über die API angelegt hat, und zwar 7 Tage lang.

curl -L -o video.mp4 \
  "https://developers.grem.capital/api/v1/artifacts/v1/ai/assistant/announcement/jobs/JOB_ID/artifacts/ARTIFACT_ID/download" \
  -H "Authorization: Bearer gsk_live_xxx"

Eine PDF-Präsentation hat zusätzlich das Feld link - die direkte Adresse des Dokuments.

Verwandte Artikel

War dieser Artikel hilfreich?