> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Vettorizzare un'immagine
> Invia un job di vettorizzazione — un'immagine sorgente verso SVG — e ottieni un id del job.
Vettorizza una `image` sorgente in un SVG. La chiamata restituisce **`202 Accepted`**
con un `id` del job; interroga
[`GET /images/vectorizations/{id}`](/it/api-reference/image-ops/get-vectorization) per
il risultato. L'`image` prende **esattamente uno** tra `image_id`, `url` o
`base64` + `mime_type`. Non c'è **alcun parametro di modello**. Richiede lo scope
`images.transform`.
**L'SVG è un'esclusione di ambito ai sensi dell'art. 50(2) del EU AI Act.** Un SVG
non può contenere né un manifesto C2PA né una filigrana incorporata, quindi gli
output vettoriali sono consegnati **non firmati e senza filigrana**. La consegna è
vincolata a `svg_acceptance` — un riconoscimento esplicito di questo. **Il
riconoscimento è una prova di divulgazione / audit, non una rinuncia alla
conformità.**
## Esempio: una sorgente per modalità
`svg_acceptance` deve essere il booleano letterale `true` a ogni richiesta:
```bash image_id theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/vectorizations \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"svg_acceptance": true
}'
```
```bash url theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/vectorizations \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "url": "https://cdn.example.com/logo.png" },
"svg_acceptance": true,
"webhook_url": "https://example.com/webhooks/samsa"
}'
```
```bash base64 theme={null}
curl -X POST https://api.samsa.ai/public/v1/images/vectorizations \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" },
"svg_acceptance": true
}'
```
Il percorso normale (addebitato) restituisce un job `pending`:
```json 202 Accepted theme={null}
{
"id": "a8b9c0d1-2e3f-4a4b-5c6d-7e8f9a0b1c2d",
"status": "pending",
"estimated_credits": 5
}
```
**Costo = 5 credits su un miss; 0 su un cache hit.** Quando la sorgente è un
`image_id` che possiedi e per esso esiste già un risultato vettoriale, l'invio
restituisce immediatamente `202` con `status: "completed"` e
`estimated_credits: 0` — nessun nuovo job viene messo in coda e il limite di
concorrenza della tua organizzazione non viene consumato.
## Gate di accettazione
La vettorizzazione ha due gate di consegna indipendenti, entrambi applicati **senza
addebito** in caso di errore:
* `svg_acceptance` deve essere il booleano letterale `true`. Un valore mancante,
`false` o altro è rifiutato con `422 svg_acceptance_required`.
* È richiesta anche un'**accettazione ToS/AUP attuale e verificata lato server** — il
flag della richiesta non è mai considerato come questo fatto. Un'accettazione
mancante o scaduta è rifiutata con `403 svg_phase1_scope_out_required`; accetta gli
attuali ToS/AUP e riprova.
## Errori
| Stato | Codice | Quando |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402` | [`insufficient_credits`](/it/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/it/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/it/guides/errors#insufficient_unallocated_credits) | Il saldo che questa credenziale può spendere è al di sotto del costo del job. Le organizzazioni con almeno un team attivo ricevono i codici legati ai team invece di `insufficient_credits` (eccetto le organizzazioni di sistema esenti dal budgeting per team). Un guasto operativo nella detrazione stessa può comunque restituire il generico `insufficient_credits`, qualunque sia il regime. |
| `402` | [`subscription_inactive`](/it/guides/errors#subscription_inactive) | L'organizzazione non ha un abbonamento utilizzabile. |
| `403` | [`missing_scope`](/it/guides/errors#missing_scope) | La chiave non ha lo scope `images.transform`. |
| `403` | [`svg_phase1_scope_out_required`](/it/guides/errors#svg_phase1_scope_out_required) | L'accettazione di esclusione di ambito ToS/AUP verificata lato server è mancante o scaduta (nessun addebito). |
| `404` | [`not_found`](/it/guides/errors#not_found) | L'`image_id` sorgente è sconosciuto o non appartiene al creatore della chiave — anche un'immagine creata da un altro membro della tua organizzazione è un `404`. |
| `422` | [`validation_error`](/it/guides/errors#validation_error) | Zero o più modalità sorgente fornite. |
| `422` | [`svg_acceptance_required`](/it/guides/errors#svg_acceptance_required) | `svg_acceptance` non è il booleano letterale `true` (nessun addebito). |
| `429` | [`rate_limited`](/it/guides/errors#rate_limited) / [`too_many_active_jobs`](/it/guides/errors#too_many_active_jobs) | Finestra di frequenza per chiave o limite di concorrenza per organizzazione superato. |
## OpenAPI
````yaml api-reference/openapi.json POST /images/vectorizations
openapi: 3.1.0
info:
title: Samsa API
description: >-
The Samsa public REST API. Authenticate with an organization API key as a
bearer token (`Authorization: Bearer samsa_sk_...`). Errors follow a single
envelope shape; every response carries an `X-Request-ID`.
version: 1.0.0
servers:
- url: https://api.samsa.ai/public/v1
security:
- BearerAuth: []
paths:
/images/vectorizations:
post:
tags:
- Images
summary: Vectorize an image to SVG (Art. 50(2) scope-out)
description: >-
Submits a vectorization job — one source `image` — and returns `202`
immediately with the job `id` and a credit estimate; poll `GET
/images/vectorizations/{id}` for the result (an SVG). The source is
exactly one of `image_id` (an image in your organization's context), an
https `url`, or `base64`+`mime_type`. There is NO model parameter. **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. `svg_acceptance` must be the literal boolean `true` to
acknowledge this — the acknowledgment is disclosure / audit evidence,
NOT a compliance waiver; a missing / `false` / other value returns `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 returns `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 already exists for it, the submit returns `202` with
`status: "completed"` and `estimated_credits: 0` immediately — no new
job is queued and the per-org concurrency cap is not consumed (an at-cap
org still gets its cached result); if a `webhook_url` was given the
`completed` event fires right away. Every other case (an https
`url`/`base64` source, or an owned `image_id` with no ready result) is
the normal charged path: `202` with `status: "pending"` and
`estimated_credits: 5`. Common errors: a foreign or unknown `image_id`
returns `404`; missing credits or no usable org subscription returns
`402`; the per-key rate limit or per-org concurrency cap returns `429`.
Requires the `images.transform` scope.
operationId: create_image_vectorization_images_vectorizations_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicVectorizationRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicTransformAccepted'
'401':
description: Missing, invalid, expired, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'402':
description: Insufficient credits, or no usable org subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: The API key lacks the required scope for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Generation, or a referenced model/palette, not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'409':
description: A referenced model is not ready for generation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'422':
description: Request validation failed (prompt, engine, resolution, ...).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Per-key rate limit or per-org concurrency cap exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
schemas:
PublicVectorizationRequest:
properties:
image:
$ref: '#/components/schemas/PublicImageEditSource'
description: >-
The source image: exactly one of `image_id`, an https `url`, or
`base64`+`mime_type`.
svg_acceptance:
type: boolean
const: true
title: Svg Acceptance
description: >-
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.
examples:
- true
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: >-
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.
examples:
- https://example.com/webhooks/samsa
type: object
required:
- image
- svg_acceptance
title: PublicVectorizationRequest
description: >-
`POST /images/vectorizations` body (SAM-821 / S8.9 — Art. 50(2)
scope-out).
Vectorize ONE source `image` into an SVG (Recraft; 5 credits flat). The
source
is exactly one of `image_id` (an image in your organization's context),
an
https `url`, or `base64`+`mime_type`. There is NO model parameter.
**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 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).
examples:
- image:
image_id: 123e4567-e89b-12d3-a456-426614174000
svg_acceptance: true
- image:
url: https://cdn.example.com/logo.png
svg_acceptance: true
webhook_url: https://example.com/webhooks/samsa
- image:
base64: iVBORw0KGgoAAAANSUhEUg...
mime_type: image/png
svg_acceptance: true
PublicTransformAccepted:
properties:
id:
type: string
format: uuid
title: Id
description: The job id — poll the op's `GET .../{id}` endpoint.
status:
$ref: '#/components/schemas/PublicImageStatus'
description: >-
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).
examples:
- pending
estimated_credits:
type: integer
title: Estimated Credits
description: >-
Credits this job is expected to cost — `0` on a cache-hit
`completed` response.
examples:
- 5
type: object
required:
- id
- status
- estimated_credits
title: PublicTransformAccepted
description: >-
Shared `202` body for the transform-op submits (SAM-813 / S8 wave).
Every `POST /images/` 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`.
ErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorEnvelope
description: The complete public error body — an ``error`` object wrapper (ADR §5).
PublicImageEditSource:
properties:
image_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Image Id
description: Id of an image in your organization's context to edit.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: https URL of the source image (downloaded under SSRF guards).
examples:
- https://cdn.example.com/photo.png
base64:
anyOf:
- type: string
- type: 'null'
title: Base64
description: Base64-encoded source image bytes (send with `mime_type`).
mime_type:
anyOf:
- type: string
- type: 'null'
title: Mime Type
description: >-
MIME type for a base64 source — one of: image/jpeg, image/png,
image/webp.
examples:
- image/png
type: object
title: PublicImageEditSource
description: >-
The source image for an edit — exactly one of three modes (ticket §1).
* `image_id` — an image already in the key creator's context (owned by
the key
creator; ownership is enforced in the route -> `404` on a miss).
* `url` — an `https` URL the server downloads under the SSRF guard
(§7.4).
* `base64` + `mime_type` — inline bytes (`mime_type` in the allow-list).
Exactly one mode must be supplied; zero or more than one is a `422`.
`url` / `base64` rasters must decode to at most **33,554,432 pixels**
(32 MP, width x height) — a larger source returns `422` naming the
source
param, before any charge (same ceiling the resize op documents).
PublicImageStatus:
type: string
enum:
- pending
- processing
- completed
- failed
- cancelled
title: PublicImageStatus
description: >-
Public image-job status — the lower-cased internal ``TaskStatus``.
Deliberately the plain lower-cased internal value (NOT the ADR §7.2
``PENDING -> queued`` remap): the ticket's 202 uses ``status:
"pending"`` and
its fixtures say ``pending/processing/completed/failed``, and this keeps
the
public surface consistent with the already-shipped models API
(``PublicModelStatus``).
ErrorDetail:
properties:
type:
type: string
title: Type
examples:
- authentication_error
code:
type: string
title: Code
examples:
- invalid_api_key
message:
type: string
title: Message
examples:
- The provided API key is invalid, expired, or revoked.
request_id:
type: string
title: Request Id
examples:
- 8f14e45fceea167a5a36dedd4bea2543
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: Present on validation errors — names the offending field.
examples:
- aspect_ratio
type: object
required:
- type
- code
- message
- request_id
title: ErrorDetail
description: The ``error`` object of the public envelope (ADR §5).
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Organization API key as a bearer token: `Authorization: Bearer
samsa_sk_...`.
````