Zum Hauptinhalt springen
POST
Vectorize an image to SVG (Art. 50(2) scope-out)
Vektorisiere ein Quell-image in ein SVG. Der Aufruf gibt 202 Accepted mit einer Job-id zurück; frage GET /images/vectorizations/{id} nach dem Ergebnis ab. Das image nimmt genau eines von image_id, url oder base64 + mime_type. Die optionalen Felder engine und mode wählen den Vektorisierer (siehe Engines und Modi). Erfordert den images.transform-Scope.
SVG ist ein EU-AI-Act-Art.-50(2)-Scope-out. Ein SVG kann kein C2PA-Manifest oder eingebettetes Wasserzeichen tragen, daher werden Vektorausgaben unsigniert und ohne Wasserzeichen ausgeliefert. Die Auslieferung ist an svg_acceptance gebunden — eine ausdrückliche Bestätigung dessen. Die Bestätigung ist Offenlegungs-/Prüfnachweis, kein Compliance-Verzicht.

Beispiel: eine Quelle pro Modus

svg_acceptance muss bei jeder Anfrage der literale Boolean true sein:
Der normale (abgerechnete) Pfad gibt einen pending-Job zurück:
202 Accepted
Kosten = 5 Credits bei einem Miss (jede Engine und jeder Modus); 0 bei einem Cache-Treffer. Wenn die Quelle eine image_id ist, die du besitzt, und bereits ein Vektorergebnis derselben engine und desselben mode 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.

Engines und Modi

  • Lass engine weg, um recraft zu verwenden. Eine Anfrage ohne engine und mode funktioniert wie bisher.
  • mode ist nur mit engine: "ideogram" gültig. Mit ideogram ist ein fehlender mode gleich default.
  • Eine unbekannte engine oder ein unbekannter mode, oder ein mode mit recraft (auch wenn engine fehlt), gibt 422 validation_error zurück, bevor etwas belastet wird.
  • Die Kosten sind bei jeder Engine und jedem Modus gleich: 5 Credits bei einem Miss.
  • Der Cache gilt pro Quellbild und Engine und Modus: Ein recraft-Ergebnis erfüllt keine ideogram-Anfrage, und ein ideogram-Ergebnis im Modus default erfüllt keine Anfrage im Modus simple.
Ideogram, Modus simple

Freigabe-Gates

Die Vektorisierung hat zwei unabhängige Auslieferungs-Gates, beide bei einem Fehler ohne Abrechnung durchgesetzt:
  • svg_acceptance muss der literale Boolean true sein. Ein fehlender, false- oder anderer Wert wird mit 422 svg_acceptance_required abgelehnt.
  • Eine aktuelle, serverseitig verifizierte ToS/AUP-Zustimmung ist ebenfalls erforderlich — das Anfrage-Flag wird niemals als dieser Fakt vertraut. Eine fehlende oder veraltete Zustimmung wird mit 403 svg_phase1_scope_out_required abgelehnt; akzeptiere die aktuellen ToS/AUP und versuche es erneut.

Fehler

Autorisierungen

Authorization
string
header
erforderlich

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

Body

application/json

POST /images/vectorizations body (SAM-821 / S8.9 — Art. 50(2) scope-out).

Vectorize ONE source image into an SVG (5 credits flat, every engine and mode). The source is exactly one of image_id (an image in your organization's context), an https url, or base64+mime_type. Optional engine: recraft (the default) or ideogram; mode (default | simple) is valid only with ideogram and defaults to default.

SVG is a documented EU AI Act Art. 50(2) scope-out: an SVG cannot carry a C2PA manifest or an embedded watermark, so vector outputs are delivered unsigned. Delivery is therefore gated on svg_acceptance — an explicit acknowledgment that the SVG is an unsigned, unwatermarked scope-out output. This acknowledgment is disclosure / audit evidence, NOT a compliance waiver. svg_acceptance must be the literal boolean true; a missing, false, or any other value is rejected 422 svg_acceptance_required with no charge. Delivery ALSO requires a current, server-verified ToS/AUP acceptance (the request flag is never trusted as that fact); a missing / stale acceptance is 403 svg_phase1_scope_out_required with no charge.

Cost = 5 credits on a miss; 0 on a cache HIT. When the source is an image_id you own and a vector result from the SAME engine and mode already exists for it, the submit returns 202 with status: "completed" and estimated_credits: 0 immediately (no new job is queued and the org's concurrency cap is not consumed).

image
PublicImageEditSource · object
erforderlich

The source image: exactly one of image_id, an https url, or base64+mime_type.

svg_acceptance
boolean
erforderlich

Must be the literal boolean true: an explicit acknowledgment that SVG (vector) output is an EU AI Act Art. 50(2) scope-out delivered UNSIGNED and UNWATERMARKED. This acknowledgment is disclosure / audit evidence, NOT a compliance waiver. Any other value (missing / false) is rejected 422 svg_acceptance_required with no charge.

Beispiel:

true

webhook_url
string | null

Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs). On a cache hit the completed event fires immediately.

Beispiel:

"https://example.com/webhooks/samsa"

engine
enum<string> | null

Optional vectorize engine: recraft (the default when omitted) or ideogram. Every engine costs the same 5 credits.

Verfügbare Optionen:
recraft,
ideogram
Beispiel:

"ideogram"

mode
enum<string> | null

Optional Ideogram mode: default (detailed, the default when omitted) or simple. Valid ONLY with engine ideogram; any other combination is rejected 422 with no charge.

Verfügbare Optionen:
default,
simple
Beispiel:

"simple"

Antwort

Successful Response

Shared 202 body for the transform-op submits (SAM-813 / S8 wave).

Every POST /images/<op> returns the async job handle {id, status, estimated_credits}. The initial status is pending (the job is queued), with ONE exception: background-removals and vectorizations answer an owned-image_id cache hit (a ready result already exists for that image) with status: "completed" and estimated_credits: 0 — no new job is queued, the completed webhook event is emitted immediately for a supplied webhook_url, and the result is already available from the op's GET .../{id} endpoint. The other transform ops (img2img, variations, resizes, upscales) always start pending.

id
string<uuid>
erforderlich

The job id — poll the op's GET .../{id} endpoint.

status
enum<string>
erforderlich

Initial status: pending (job queued — enter the polling flow), or completed with estimated_credits: 0 when background-removals / vectorizations serve an owned-image cache hit (the result is immediately available).

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

"pending"

estimated_credits
integer
erforderlich

Credits this job is expected to cost — 0 on a cache-hit completed response.

Beispiel:

5