curl --request PATCH \
--url https://api.samsa.ai/public/v1/models/{model_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Renamed Model",
"default_prompt": "A refined flat-design illustration in the Acme brand palette.",
"instruction": "Always render on a clean, seamless white background."
}
'import requests
url = "https://api.samsa.ai/public/v1/models/{model_id}"
payload = {
"name": "Renamed Model",
"default_prompt": "A refined flat-design illustration in the Acme brand palette.",
"instruction": "Always render on a clean, seamless white background."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Renamed Model',
default_prompt: 'A refined flat-design illustration in the Acme brand palette.',
instruction: 'Always render on a clean, seamless white background.'
})
};
fetch('https://api.samsa.ai/public/v1/models/{model_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/models/{model_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Renamed Model',
'default_prompt' => 'A refined flat-design illustration in the Acme brand palette.',
'instruction' => 'Always render on a clean, seamless white background.'
]),
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/models/{model_id}"
payload := strings.NewReader("{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.samsa.ai/public/v1/models/{model_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/models/{model_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Acme Brand Style",
"status": "completed",
"is_ready": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "style",
"thumbnail_url": "https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…",
"reference_image_urls": [
"https://cdn.samsa.ai/models/…/ref-0.webp?X-Amz-Signature=…"
],
"user_instruction": "Use for hero banners and social posts.",
"default_prompt": "A bold flat-design illustration in the Acme brand palette.",
"trigger_words": [
"acme"
]
}{
"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"
}
}Aggiorna un modello
Aggiorna i campi modificabili (nome, prompt predefinito, istruzione) di uno dei tuoi modelli.
curl --request PATCH \
--url https://api.samsa.ai/public/v1/models/{model_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Renamed Model",
"default_prompt": "A refined flat-design illustration in the Acme brand palette.",
"instruction": "Always render on a clean, seamless white background."
}
'import requests
url = "https://api.samsa.ai/public/v1/models/{model_id}"
payload = {
"name": "Renamed Model",
"default_prompt": "A refined flat-design illustration in the Acme brand palette.",
"instruction": "Always render on a clean, seamless white background."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Renamed Model',
default_prompt: 'A refined flat-design illustration in the Acme brand palette.',
instruction: 'Always render on a clean, seamless white background.'
})
};
fetch('https://api.samsa.ai/public/v1/models/{model_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/models/{model_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Renamed Model',
'default_prompt' => 'A refined flat-design illustration in the Acme brand palette.',
'instruction' => 'Always render on a clean, seamless white background.'
]),
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/models/{model_id}"
payload := strings.NewReader("{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.samsa.ai/public/v1/models/{model_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/models/{model_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Renamed Model\",\n \"default_prompt\": \"A refined flat-design illustration in the Acme brand palette.\",\n \"instruction\": \"Always render on a clean, seamless white background.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Acme Brand Style",
"status": "completed",
"is_ready": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"category": "style",
"thumbnail_url": "https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…",
"reference_image_urls": [
"https://cdn.samsa.ai/models/…/ref-0.webp?X-Amz-Signature=…"
],
"user_instruction": "Use for hero banners and social posts.",
"default_prompt": "A bold flat-design illustration in the Acme brand palette.",
"trigger_words": [
"acme"
]
}{
"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"
}
}name, default_prompt e instruction sono modificabili; i campi di proprietà e privacy
non possono essere modificati. instruction è la guida sempre applicata del modello (max. 8000 caratteri),
iniettata come direttiva obbligatoria (“MUST FOLLOW”) in ogni generazione di immagini e video che compone il
modello — corrisponde allo user_instruction restituito in lettura del modello.
Ometti un campo per lasciarlo invariato — non inviarlo come null esplicito (invia una stringa vuota per
cancellare instruction). Gli id sconosciuti o di un’altra organizzazione restituiscono
404 not_found. Richiede lo scope models.write.Autorizzazioni
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Parametri del percorso
Corpo
PATCH /models/{id} body — the publicly editable fields only (ADR §10, ticket §3).
Ownership / privacy fields (owner_id, private, organization_id) are
intentionally NOT accepted. A field may be omitted (left unchanged) but must not
be sent as an explicit null — the runtime rejection lives in
_reject_explicit_null (mirroring ApiKeyUpdate), and
_string_only_patch_schema keeps the EXPORTED OpenAPI honest by advertising
each field as a plain string (no null branch) so generated clients and
the API playground cannot offer null as a value (SAM-639).
New model name.
1 - 100"Renamed Model"
New default prompt / capability description.
2000"A refined flat-design illustration in the Acme brand palette."
New always-applied model instruction (max 8000 chars) — injected into every generation that composes the model. Accepted on write under the name instruction (mirroring model creation); it maps to the user_instruction field returned on read (PublicModelDetail).
8000"Always render on a clean, seamless white background."
Risposta
Successful Response
A single model with full detail — the GET /models/{id} body (ADR §10).
"Acme Brand Style"
Creation status: pending, processing, completed, or failed.
pending, processing, completed, failed "completed"
True when the model is completed AND active — usable for generation.
true
Model category — one of style, object, person, setting.
style, object, person, setting "style"
Presigned, time-limited HTTPS thumbnail URL (null when the model has none).
"https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…"
Presigned, time-limited HTTPS URLs of the reference images used to create the model.
[
"https://cdn.samsa.ai/models/…/ref-0.webp?X-Amz-Signature=…"
]
Free-text guidance for how to use the model.
"Use for hero banners and social posts."
The model's default prompt / capability description.
"A bold flat-design illustration in the Acme brand palette."
Trigger words associated with the model.
["acme"]

