curl --request POST \
--url https://api.samsa.ai/public/v1/images/upscales \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": {
"image_id": "123e4567-e89b-12d3-a456-426614174000"
},
"model": "crystal",
"target_resolution": "4K"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/upscales"
payload = {
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "crystal",
"target_resolution": "4K"
}
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: '123e4567-e89b-12d3-a456-426614174000'},
model: 'crystal',
target_resolution: '4K'
})
};
fetch('https://api.samsa.ai/public/v1/images/upscales', 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/upscales",
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' => '123e4567-e89b-12d3-a456-426614174000'
],
'model' => 'crystal',
'target_resolution' => '4K'
]),
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/upscales"
payload := strings.NewReader("{\n \"image\": {\n \"image_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\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/upscales")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": {\n \"image_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/upscales")
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\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"estimated_credits": 5
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}Ingrandire un'immagine
Invia un job di upscale — un’immagine sorgente verso una risoluzione target superiore — e ottieni un id del job.
curl --request POST \
--url https://api.samsa.ai/public/v1/images/upscales \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image": {
"image_id": "123e4567-e89b-12d3-a456-426614174000"
},
"model": "crystal",
"target_resolution": "4K"
}
'import requests
url = "https://api.samsa.ai/public/v1/images/upscales"
payload = {
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "crystal",
"target_resolution": "4K"
}
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: '123e4567-e89b-12d3-a456-426614174000'},
model: 'crystal',
target_resolution: '4K'
})
};
fetch('https://api.samsa.ai/public/v1/images/upscales', 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/upscales",
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' => '123e4567-e89b-12d3-a456-426614174000'
],
'model' => 'crystal',
'target_resolution' => '4K'
]),
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/upscales"
payload := strings.NewReader("{\n \"image\": {\n \"image_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\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/upscales")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"image\": {\n \"image_id\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/upscales")
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\": \"123e4567-e89b-12d3-a456-426614174000\"\n },\n \"model\": \"crystal\",\n \"target_resolution\": \"4K\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "pending",
"estimated_credits": 5
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}image sorgente verso una target_resolution superiore con uno dei
quattro modelli. La chiamata restituisce 202 Accepted con un id del job;
interroga GET /images/upscales/{id} per
il risultato. L’image prende esattamente uno tra image_id, url o
base64 + mime_type. Richiede lo scope images.transform.
Esempio: una sorgente per modalità
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "crystal",
"target_resolution": "4K"
}'
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "url": "https://cdn.example.com/photo.png" },
"model": "seedvr",
"target_resolution": "2K"
}'
curl -X POST https://api.samsa.ai/public/v1/images/upscales \
-H "Authorization: Bearer $SAMSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" },
"model": "magnific-precision",
"target_resolution": "6K",
"options": { "magnific_precision": { "flavor": "photo", "sharpen": 20, "ultra_detail": 40 } }
}'
Esempio: magnific-creative con opzioni
{
"image": { "image_id": "123e4567-e89b-12d3-a456-426614174000" },
"model": "magnific-creative",
"target_resolution": "8K",
"options": {
"magnific_creative": {
"prompt": "sharp studio product photo",
"optimized_for": "films_n_photography",
"creativity": 2,
"hdr": 1,
"engine": "magnific_sharpy"
}
},
"webhook_url": "https://example.com/webhooks/samsa"
}
202 è l’handle del job asincrono:
{
"id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
"status": "pending",
"estimated_credits": 75
}
model è crystal (predefinito), seedvr, magnific-creative o
magnific-precision. target_resolution è obbligatorio e tratto da un insieme
chiuso: 2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K,
32K, 38K. Le classi oltre 16K sono valide solo per crystal. I limiti di
fattore e area per modello sono validati prima di qualsiasi addebito — una
richiesta oltre il limite è un 422, mai un job addebitato.options sono per modello, tipizzate e validate rigorosamente: fornisci
magnific_creative per il modello magnific-creative o magnific_precision per
magnific-precision. seedvr e crystal non prendono opzioni — fornire options
per loro è un 422. Chiavi sconosciute o valori fuori intervallo sono un 422.magnific_creative:prompt(≤ 500 caratteri),optimized_for(standard·soft_portraits·hard_portraits·art_n_illustration·videogame_assets·nature_n_landscapes·films_n_photography·3d_renders·science_fiction_n_horror),creativity/hdr/resemblance/fractality(interi −10…10),engine(automatic·magnific_illusio·magnific_sharpy·magnific_sparkle).magnific_precision:sharpen/smart_grain/ultra_detail(interi 0…100),flavor(sublime(predefinito) ·photo·photo_denoiser).
Credits
Il costo è il livello di risoluzione (2K:5, 4K:10, 6K:20, 8K:25, 10K:35,
12K:45, 14K:60, 16K:80) moltiplicato per il moltiplicatore di credits del
modello (Magnific ×3); Crystal oltre 12K addebita per megapixel di output. Gli
estimated_credits nella risposta 202 corrispondono esattamente all’addebito. Vedi
Prezzi.
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. |
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/più modalità sorgente, target_resolution mancante/non valido, una classe oltre il limite o options non valide/mal posizionate. |
429 | rate_limited / too_many_active_jobs | Finestra di frequenza per chiave o limite di concorrenza per organizzazione superato. |
Autorizzazioni
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Corpo
POST /images/upscales body (SAM-819 / S8.7 — ADR §7, §8, §10).
Upscale ONE source image to a higher target_resolution with one of the
four public models. The source is exactly one of image_id (an image in
your organization's context), an https url, or base64+mime_type.
target_resolution is a CLOSED set — the per-model factor/area caps are
validated BEFORE charging (an over-cap request is a 422, never a charged
job). options are per-model, typed, and STRICTLY validated (out-of-range /
unknown values are 422 — a documented deviation from the app's clamping).
Cost is the existing upscale estimator: the resolution tier
(2K:5, 4K:10, 6K:20, 8K:25, 10K:35, 12K:45, 14K:60, 16K:80) x the model
credit multiplier (Magnific x3); Crystal above 12K prices by output
megapixels. estimated_credits in the 202 equals the deduction exactly.
The source image: exactly one of image_id, an https url, or base64+mime_type.
Show child attributes
Show child attributes
Target resolution class (REQUIRED) — one of 2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K, 32K, 38K. Classes above 16K are only valid for crystal. The per-model factor/area caps are validated before charging.
2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K, 32K, 38K "4K"
Upscale model: seedvr, crystal (default), magnific-creative, or magnific-precision.
seedvr, crystal, magnific-creative, magnific-precision "crystal"
Per-model tuning options (typed). Only magnific-creative and magnific-precision accept options — supplying options for seedvr/crystal is a 422.
Show child attributes
Show child attributes
Optional https webhook notified once on terminal status (signed per the webhook signature scheme; see the webhooks docs).
"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.
The job id — poll the op's GET .../{id} endpoint.
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).
pending, processing, completed, failed, cancelled "pending"
Credits this job is expected to cost — 0 on a cache-hit completed response.
5

