Passer au contenu principal
POST
Vectorize an image to SVG (Art. 50(2) scope-out)
Vectorise une image source en SVG. L’appel renvoie 202 Accepted avec un id de job ; interroge GET /images/vectorizations/{id} pour le résultat. L’image prend exactement un de image_id, url ou base64 + mime_type. Les champs optionnels engine et mode choisissent le vectoriseur (voir Moteurs et modes). Requiert le scope images.transform.
Le SVG est une exclusion de périmètre au titre de l’art. 50(2) du EU AI Act. Un SVG ne peut porter ni manifeste C2PA ni filigrane intégré, donc les sorties vectorielles sont livrées non signées et sans filigrane. La livraison est conditionnée à svg_acceptance — une reconnaissance explicite de ce fait. La reconnaissance est une preuve de divulgation / d’audit, pas une renonciation à la conformité.

Exemple : une source par mode

svg_acceptance doit être le booléen littéral true à chaque requête :
Le chemin normal (facturé) renvoie un job pending :
202 Accepted
Coût = 5 credits sur un miss (chaque moteur et chaque mode) ; 0 sur un hit de cache. Quand la source est un image_id que tu possèdes et qu’un résultat vectoriel du même engine et du même mode existe déjà pour lui, la soumission renvoie immédiatement 202 avec status: "completed" et estimated_credits: 0 — aucun nouveau job n’est mis en file et le plafond de concurrence de ton organisation n’est pas consommé.

Moteurs et modes

  • Omets engine pour utiliser recraft. Une requête sans engine ni mode fonctionne comme avant.
  • mode est valide uniquement avec engine: "ideogram". Avec ideogram, un mode omis vaut default.
  • Un engine ou un mode inconnu, ou un mode avec recraft (aussi quand engine est omis), renvoie 422 validation_error avant tout débit.
  • Le coût est le même pour chaque moteur et chaque mode : 5 credits sur un miss.
  • Le cache est par image source et par moteur et mode : un résultat recraft ne satisfait pas une requête ideogram, et un résultat ideogram en mode default ne satisfait pas une requête en mode simple.
Ideogram, mode simple

Portails d’acceptation

La vectorisation a deux portails de livraison indépendants, tous deux appliqués sans facturation en cas d’échec :
  • svg_acceptance doit être le booléen littéral true. Une valeur manquante, false ou autre est rejetée par 422 svg_acceptance_required.
  • Une acceptation ToS/AUP actuelle et vérifiée côté serveur est également requise — le flag de la requête n’est jamais considéré comme ce fait. Une acceptation manquante ou périmée est rejetée par 403 svg_phase1_scope_out_required ; accepte les ToS/AUP actuels et réessaie.

Erreurs

Autorisations

Authorization
string
header
requis

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

Corps

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
requis

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

svg_acceptance
boolean
requis

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.

Exemple:

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.

Exemple:

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

Options disponibles:
recraft,
ideogram
Exemple:

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

Options disponibles:
default,
simple
Exemple:

"simple"

Réponse

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>
requis

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

status
enum<string>
requis

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).

Options disponibles:
pending,
processing,
completed,
failed,
cancelled
Exemple:

"pending"

estimated_credits
integer
requis

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

Exemple:

5