curl --request GET \
--url https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}', 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/background-removals/{background_removal_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "completed",
"created_at": "2023-11-07T05:31:56Z",
"credits_used": 1,
"image": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"format_type": "upscale",
"mime_type": "image/png",
"url": "https://cdn.samsa.ai/user-.../abc.png?X-Amz-Signature=...",
"width": 123,
"height": 123,
"resolution_class": "2K",
"model": "crystal"
},
"error": "<string>"
}{
"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"
}
}Récupérer un job de suppression d'arrière-plan
Interroge un job de suppression d’arrière-plan pour son statut et, une fois terminé, le PNG transparent.
curl --request GET \
--url https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}', 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/background-removals/{background_removal_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/images/background-removals/{background_removal_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "completed",
"created_at": "2023-11-07T05:31:56Z",
"credits_used": 1,
"image": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_image_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"format_type": "upscale",
"mime_type": "image/png",
"url": "https://cdn.samsa.ai/user-.../abc.png?X-Amz-Signature=...",
"width": 123,
"height": 123,
"resolution_class": "2K",
"model": "crystal"
},
"error": "<string>"
}{
"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"
}
}pending
ou processing, continue d’interroger ; une fois completed, la réponse porte un
seul objet résultat image — un PNG transparent avec une presigned url valable
24 heures. Un job en hit de cache naît completed avec son résultat déjà
attaché. Seuls les jobs créés par ton organisation sont visibles ; tout autre id
renvoie 404 not_found. Requiert le scope
images.transform.
Exemple : job terminé
L’image est un objet résultat de format dérivé ; pour la suppression
d’arrière-plan, model, width et height sont toujours null. Cet exemple est un
hit de cache, donc credits_used vaut 0 (un miss normal affiche 1) :
{
"id": "f7a8b9c0-1d2e-4f3a-4b5c-6d7e8f9a0b1c",
"status": "completed",
"created_at": "2026-07-18T10:12:00Z",
"credits_used": 0,
"image": {
"id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
"source_image_id": "123e4567-e89b-12d3-a456-426614174000",
"format_type": "background_removal",
"mime_type": "image/png",
"url": "https://cdn.samsa.ai/user-.../no-bg.png?X-Amz-Signature=...",
"width": null,
"height": null,
"resolution_class": null,
"model": null
},
"error": null
}
webhook_url sur la
requête de suppression d’arrière-plan
d’origine pour recevoir un callback signé au lieu d’interroger — sur un hit de
cache, l’événement completed se déclenche immédiatement. Voir
Webhooks.Autorisations
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Paramètres de chemin
Réponse
Successful Response
GET /images/background-removals/{id} body (SAM-820 / S8.8 — ADR §7.2).
The standard async-job envelope plus ONE nullable image result object (an
image_formats derivative — a transparent PNG — built by the S8.2 egress
builder; model/width/height are always null for background removal).
created_at is the job's submit time from the credit ledger (the
image_generation_tasks table has no created_at column). A cache-hit job is
born completed with a frozen result; a normal job progresses
pending → processing → completed/failed.
pending, processing, completed, failed, or cancelled.
pending, processing, completed, failed, cancelled "completed"
When the job was submitted.
Net credits charged for this job, after any refunds (0 for a cache hit).
1
The produced transparent PNG (presigned URL); null until completed.
Show child attributes
Show child attributes
Failure detail when status is failed; otherwise null.

