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"
}
}Agrandir une image
Soumets un job d’upscale — une image source vers une résolution cible supérieure — et récupère un id de 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 source vers une target_resolution supérieure avec l’un des
quatre modèles. L’appel renvoie 202 Accepted avec un id de job ; interroge
GET /images/upscales/{id} pour le
résultat. L’image prend exactement un de image_id, url ou
base64 + mime_type. Requiert le scope images.transform.
Exemple : une source par mode
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 } }
}'
Exemple : magnific-creative avec options
{
"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 est le handle de job asynchrone :
{
"id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
"status": "pending",
"estimated_credits": 75
}
model est crystal (défaut), seedvr, magnific-creative ou
magnific-precision. target_resolution est requis et tiré d’un ensemble
fermé : 2K, 4K, 6K, 8K, 10K, 12K, 14K, 16K, 20K, 24K, 28K,
32K, 38K. Les classes au-dessus de 16K ne sont valides que pour crystal.
Les plafonds de facteur et d’aire par modèle sont validés avant toute
facturation — une requête au-dessus du plafond est un 422, jamais un job facturé.options sont par modèle, typées et validées strictement : fournis
magnific_creative pour le modèle magnific-creative ou magnific_precision pour
magnific-precision. seedvr et crystal ne prennent aucune option — fournir
options pour eux est un 422. Les clés inconnues ou les valeurs hors plage sont
un 422.magnific_creative:prompt(≤ 500 caractères),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(entiers −10…10),engine(automatic·magnific_illusio·magnific_sharpy·magnific_sparkle).magnific_precision:sharpen/smart_grain/ultra_detail(entiers 0…100),flavor(sublime(défaut) ·photo·photo_denoiser).
Credits
Le coût est le palier de résolution (2K:5, 4K:10, 6K:20, 8K:25, 10K:35,
12K:45, 14K:60, 16K:80) multiplié par le multiplicateur de credits du modèle
(Magnific ×3) ; Crystal au-dessus de 12K facture par mégapixels de sortie. Les
estimated_credits de la réponse 202 correspondent exactement au débit. Voir
Tarifs.
Erreurs
| Statut | Code | Quand |
|---|---|---|
402 | insufficient_credits / insufficient_team_credits / insufficient_unallocated_credits | Le solde que ce credential peut dépenser est en dessous du coût du job. Les organisations avec au moins une équipe active reçoivent les codes liés aux équipes à la place de insufficient_credits (sauf les organisations système exemptées du budgeting par équipe). Une défaillance opérationnelle dans la déduction elle-même peut néanmoins renvoyer le générique insufficient_credits, quel que soit le régime. |
402 | subscription_inactive | L’organisation n’a aucun abonnement utilisable. |
403 | missing_scope | La clé n’a pas le scope images.transform. |
404 | not_found | L’image_id source est inconnu ou n’appartient pas au créateur de la clé — une image créée par un autre membre de ton organisation renvoie aussi un 404. |
422 | validation_error | Zéro/plusieurs modes source, target_resolution manquant/invalide, une classe au-dessus du plafond ou des options invalides/mal placées. |
429 | rate_limited / too_many_active_jobs | Fenêtre de débit par clé ou plafond de concurrence par organisation dépassé. |
Autorisations
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Corps
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"
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.
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

