Skip to main content
Die Bildoperations-Endpunkte transformieren ein Bild, das du bereits hast — keine reine Prompt-Generierung. Sechs Operationen, jede ein POST, das einen Job einreicht, plus ein GET, das ihn abfragt:

​
Quellbild

Jede Operation nimmt ihre Quelle auf dieselben drei Arten — übergib genau einen Modus pro Quelle:
  • image_id — die id eines Bildes, das dem Key-Ersteller in Samsa gehört; jede andere id liefert 404, auch die eines Bildes, das ein anderes Mitglied deiner Organisation erstellt hat.
  • url — eine https-URL, die der Server unter seinem SSRF-Schutz herunterlädt.
  • base64 + mime_type — Inline-Bytes, mime_type eines von image/jpeg, image/png, image/webp.
Null oder mehr als ein Modus ist ein 422. Img2img akzeptiert ein images-Array (1–14 Quellen); die anderen fünf nehmen ein einzelnes image-Objekt.

​
Asynchrones Muster

Jede Einreichung gibt 202 Accepted mit einem Job-Handle { "id", "status": "pending", "estimated_credits" } zurück. Frage den GET .../{id}-Endpunkt der Operation ab, bis status gleich completed ist (oder failed/cancelled), und lies dann das Ergebnis — jedes erzeugte Asset enthält eine presigned url, 24 Stunden gültig. Übergib eine webhook_url, um statt abzufragen benachrichtigt zu werden (siehe Webhooks).
Cache-Treffer (Hintergrundentfernung & Vektorisierung). Wenn die Quelle eine image_id ist, die du besitzt, und bereits ein Ergebnis dafür existiert, gibt die Einreichung sofort 202 mit status: "completed" und estimated_credits: 0 zurück — es wird kein neuer Job eingereiht und das Concurrency-Limit deiner Organisation wird nicht belegt. Jede andere Quelle (eine https-url, base64 oder eine besessene image_id ohne fertiges Ergebnis) ist der normale, abgerechnete, asynchrone Pfad.

​
Scopes

Img2img ist eine edit-Operation und erfordert den images.edit-Scope. Die anderen fünf sind transform-Operationen und erfordern images.transform. Ein Schlüssel, dem der erforderliche Scope fehlt, erhält 403 missing_scope.

​
Credits

Die Kosten ziehen aus dem Stand, den das aufrufende Credential ausgeben kann, nicht zwingend aus dem gesamten Pool der Organisation; zu wenig davon liefert 402 insufficient_credits oder die team-bezogenen insufficient_team_credits / insufficient_unallocated_credits in Organisationen mit mindestens einem aktiven Team (vom Team-Budgeting befreite System-Organisationen bleiben beim generischen Code). Ein operativer Fehler in der Abbuchung selbst kann ebenfalls als generisches insufficient_credits erscheinen, unabhängig vom Regime. Die Seite jeder Operation nennt ihre Kostenbasis. Siehe Preise und GET /credits.