Vettorizzare un'immagine

Vectorize an image to SVG (Art. 50(2) scope-out)

curl --request POST \
  --url https://api.samsa.ai/public/v1/images/vectorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": {
    "image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "url": "https://cdn.example.com/photo.png",
    "base64": "<string>",
    "mime_type": "image/png"
  },
  "svg_acceptance": true,
  "webhook_url": "https://example.com/webhooks/samsa"
}
'

import requests

url = "https://api.samsa.ai/public/v1/images/vectorizations"

payload = {
    "image": {
        "image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "url": "https://cdn.example.com/photo.png",
        "base64": "<string>",
        "mime_type": "image/png"
    },
    "svg_acceptance": True,
    "webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: {
      image_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      url: 'https://cdn.example.com/photo.png',
      base64: '<string>',
      mime_type: 'image/png'
    },
    svg_acceptance: true,
    webhook_url: 'https://example.com/webhooks/samsa'
  })
};

fetch('https://api.samsa.ai/public/v1/images/vectorizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/images/vectorizations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image' => [
        'image_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        'url' => 'https://cdn.example.com/photo.png',
        'base64' => '<string>',
        'mime_type' => 'image/png'
    ],
    'svg_acceptance' => true,
    'webhook_url' => 'https://example.com/webhooks/samsa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/images/vectorizations"

	payload := strings.NewReader("{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/vectorizations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/images/vectorizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

POST

images

vectorizations

Vectorize an image to SVG (Art. 50(2) scope-out)

curl --request POST \
  --url https://api.samsa.ai/public/v1/images/vectorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": {
    "image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "url": "https://cdn.example.com/photo.png",
    "base64": "<string>",
    "mime_type": "image/png"
  },
  "svg_acceptance": true,
  "webhook_url": "https://example.com/webhooks/samsa"
}
'

import requests

url = "https://api.samsa.ai/public/v1/images/vectorizations"

payload = {
    "image": {
        "image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "url": "https://cdn.example.com/photo.png",
        "base64": "<string>",
        "mime_type": "image/png"
    },
    "svg_acceptance": True,
    "webhook_url": "https://example.com/webhooks/samsa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    image: {
      image_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      url: 'https://cdn.example.com/photo.png',
      base64: '<string>',
      mime_type: 'image/png'
    },
    svg_acceptance: true,
    webhook_url: 'https://example.com/webhooks/samsa'
  })
};

fetch('https://api.samsa.ai/public/v1/images/vectorizations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.samsa.ai/public/v1/images/vectorizations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image' => [
        'image_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        'url' => 'https://cdn.example.com/photo.png',
        'base64' => '<string>',
        'mime_type' => 'image/png'
    ],
    'svg_acceptance' => true,
    'webhook_url' => 'https://example.com/webhooks/samsa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.samsa.ai/public/v1/images/vectorizations"

	payload := strings.NewReader("{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/images/vectorizations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.samsa.ai/public/v1/images/vectorizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image\": {\n    \"image_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"url\": \"https://cdn.example.com/photo.png\",\n    \"base64\": \"<string>\",\n    \"mime_type\": \"image/png\"\n  },\n  \"svg_acceptance\": true,\n  \"webhook_url\": \"https://example.com/webhooks/samsa\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "estimated_credits": 123
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "aspect_ratio"
  }
}

Vettorizza una image sorgente in un SVG. La chiamata restituisce 202 Accepted con un id del job; interroga GET /images/vectorizations/{id} 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:

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
  }'

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"
  }'

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:

202 Accepted

{
  "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` / `insufficient_team_credits` / `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`	L’organizzazione non ha un abbonamento utilizzabile.
`403`	`missing_scope`	La chiave non ha lo scope `images.transform`.
`403`	`svg_phase1_scope_out_required`	L’accettazione di esclusione di ambito ToS/AUP verificata lato server è mancante o scaduta (nessun addebito).
`404`	`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`	Zero o più modalità sorgente fornite.
`422`	`svg_acceptance_required`	`svg_acceptance` non è il booleano letterale `true` (nessun addebito).
`429`	`rate_limited` / `too_many_active_jobs`	Finestra di frequenza per chiave o limite di concorrenza per organizzazione superato.

Autorizzazioni

Authorization

string

header

obbligatorio

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Corpo

application/json

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

image

PublicImageEditSource · object

obbligatorio

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

Show child attributes

svg_acceptance

boolean

obbligatorio

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.

Esempio:

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.

Esempio:

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

Risposta

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.

string<uuid>

obbligatorio

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

status

enum<string>

obbligatorio

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

Opzioni disponibili:

pending,

processing,

completed,

failed,

cancelled

Esempio:

"pending"

estimated_credits

integer

obbligatorio

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

Esempio:

5

Panoramica

Endpoint

Vettorizzare un'immagine

Esempio: una sorgente per modalità

Gate di accettazione

Errori

Autorizzazioni

Corpo

Risposta

​Esempio: una sorgente per modalità

​Gate di accettazione

​Errori

Autorizzazioni

Corpo

Risposta

Esempio: una sorgente per modalità

Gate di accettazione

Errori