Zum Hauptinhalt springen
GET
Retrieve an image generation's status and results
Rufe den Status eines Generierungs-Jobs ab. Solange er pending oder processing ist, frage weiter ab; sobald er completed ist, enthält die Antwort die erzeugten Bilder, jedes mit einer presigned url, 24 Stunden gültig — lade die Assets herunter, bevor sie ablaufen. Nur Jobs, die deine Organisation erstellt hat, sind sichtbar; jede andere id liefert 404 not_found.

Compliance-Sperren

Jeder Raster-output durchläuft Samsas Compliance-Pipeline (C2PA-Signatur und Watermarking — siehe Content Provenance), bevor die API ihn ausliefert. processing heißt, dass die outputs noch unterwegs sind — frage weiter ab. Wenn ein output dauerhaft an dieser Pipeline scheitert, meldet der Job das: Jeder blocked_images-Eintrag ist { "id", "reason" }. reason ist compliance_failed_signing (C2PA-Signatur fehlgeschlagen), compliance_failed_storage, compliance_failed_watermark oder missing_provenance_state. Ein gesperrter output wird nie herunterladbar, daher ist failed final — hör auf abzufragen.
Beispiel: alle outputs gesperrt
credits_used bleibt durch eine Compliance-Sperre unverändert. Dieselben Felder und Regeln gelten für Magic-Edit-, img2img-, Variations- und Resize-Jobs sowie für das MCP-Tool get_job_status.
Lieber Push statt Polling? Übergib eine webhook_url bei der ursprünglichen Generierungsanfrage, um einen signierten Callback zu erhalten, sobald der Job einen terminalen Status erreicht. Siehe Webhooks.

Autorisierungen

Authorization
string
header
erforderlich

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Pfadparameter

generation_id
string<uuid>
erforderlich

Antwort

Successful Response

GET /images/generations/{id} body (ADR §7.2).

created_at is the job's submit time, sourced from the credit ledger — the image_generation_tasks table has no created_at column.

id
string<uuid>
erforderlich
status
enum<string>
erforderlich

pending, processing, completed, failed, or cancelled. A job whose outputs ALL failed the compliance pipeline (for example C2PA signing) is failed with error starting delivery_blocked_compliance — a terminal state, so stop polling.

Verfügbare Optionen:
pending,
processing,
completed,
failed,
cancelled
Beispiel:

"completed"

created_at
string<date-time>
erforderlich

When the job was submitted.

credits_used
integer | null

Net credits charged for this job, after any refunds.

Beispiel:

5

images
PublicImageAsset · object[]

Produced images (presigned URLs); empty until completed.

blocked_images
PublicBlockedImage · object[]

Produced images that are permanently withheld because they failed the compliance pipeline, each with its compliance code. Empty unless a completed job delivered only some of its outputs, or a failed job was blocked by compliance.

error
string | null

Failure detail when status is failed; otherwise null. A compliance block reads delivery_blocked_compliance: <codes>, where <codes> are the blocked_images reasons.

Beispiel:

"delivery_blocked_compliance: compliance_failed_signing"