Skip to main content
PATCH
Update one of your models
Met à jour les champs modifiables d’un modèle appartenant à ton organisation et renvoie le modèle mis à jour. name, default_prompt et instruction sont modifiables ; les champs de propriété et de confidentialité ne peuvent pas être modifiés. instruction est la guidance toujours appliquée du modèle (max. 8000 caractères), injectée comme directive obligatoire (“MUST FOLLOW”) dans chaque génération d’image et de vidéo qui compose le modèle — elle correspond au user_instruction renvoyé lors de la lecture du modèle. Omets un champ pour le laisser inchangé — ne l’envoie pas comme un null explicite (envoie une chaîne vide pour effacer instruction). Les ids inconnus ou appartenant à une autre organisation renvoient 404 not_found. Nécessite le scope models.write.

Autorisations

Authorization
string
header
requis

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

Paramètres de chemin

model_id
string<uuid>
requis

Corps

application/json

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

name
string

New model name.

Required string length: 1 - 100
Exemple:

"Renamed Model"

default_prompt
string

New default prompt / capability description.

Maximum string length: 2000
Exemple:

"A refined flat-design illustration in the Acme brand palette."

instruction
string

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

Maximum string length: 8000
Exemple:

"Always render on a clean, seamless white background."

Réponse

Successful Response

A single model with full detail — the GET /models/{id} body (ADR §10).

id
string<uuid>
requis
name
string
requis
Exemple:

"Acme Brand Style"

status
enum<string>
requis

Creation status: pending, processing, completed, or failed.

Options disponibles:
pending,
processing,
completed,
failed
Exemple:

"completed"

is_ready
boolean
requis

True when the model is completed AND active — usable for generation.

Exemple:

true

created_at
string<date-time>
requis
updated_at
string<date-time>
requis
category
enum<string> | null

Model category — one of style, object, person, setting.

Options disponibles:
style,
object,
person,
setting
Exemple:

"style"

thumbnail_url
string | null

Presigned, time-limited HTTPS thumbnail URL (null when the model has none).

Exemple:

"https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…"

reference_image_urls
string[]

Presigned, time-limited HTTPS URLs of the reference images used to create the model.

Exemple:
user_instruction
string | null

Free-text guidance for how to use the model.

Exemple:

"Use for hero banners and social posts."

default_prompt
string | null

The model's default prompt / capability description.

Exemple:

"A bold flat-design illustration in the Acme brand palette."

trigger_words
string[]

Trigger words associated with the model.

Exemple: