Récupérer un job de suppression d'arrière-plan

Retrieve a background-removal job's status and result

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

}

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",
  "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",
    "mime_type": "<string>",
    "url": "<string>",
    "width": 123,
    "height": 123,
    "resolution_class": "2K",
    "model": "crystal"
  },
  "error": "<string>"
}

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

GET

images

background-removals

{background_removal_id}

Retrieve a background-removal job's status and result

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

}

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",
  "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",
    "mime_type": "<string>",
    "url": "<string>",
    "width": 123,
    "height": 123,
    "resolution_class": "2K",
    "model": "crystal"
  },
  "error": "<string>"
}

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

Récupère le statut d’un job de suppression d’arrière-plan. Tant qu’il est 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) :

200 OK

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

Passe un 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

Authorization

string

header

requis

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

Paramètres de chemin

background_removal_id

string<uuid>

requis

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.

string<uuid>

requis

status

enum<string>

requis

pending, processing, completed, failed, or cancelled.

Options disponibles:

pending,

processing,

completed,

failed,

cancelled

Exemple:

"completed"

created_at

string<date-time>

requis

When the job was submitted.

credits_used

integer | null

Net credits charged for this job, after any refunds (0 for a cache hit).

Exemple:

1

image

PublicImageFormatResult · object | null

The produced transparent PNG (presigned URL); null until completed.

Show child attributes

error

string | null

Failure detail when status is failed; otherwise null.

Vue d'ensemble

Points de terminaison

Récupérer un job de suppression d'arrière-plan

Exemple : job terminé

Autorisations

Paramètres de chemin

Réponse

​Exemple : job terminé

Autorisations

Paramètres de chemin

Réponse

Exemple : job terminé