Skip to main content
PATCH
Update one of your models
Aktualisiert die editierbaren Felder eines Modells, das deiner Organisation gehört, und gibt das aktualisierte Modell zurück. name, default_prompt und instruction sind editierbar; Eigentums- und Datenschutzfelder können nicht geändert werden. instruction ist die stets angewandte Guidance des Modells (max. 8000 Zeichen), die als verbindliche (“MUST FOLLOW”) Vorgabe in jede Bild- und Videogenerierung eingespeist wird, die das Modell komponiert — sie entspricht dem user_instruction, das beim Abruf des Modells zurückgegeben wird. Lasse ein Feld weg, um es unverändert zu lassen — sende es nicht als explizites null (sende einen leeren String, um instruction zu löschen). Unbekannte oder zu einer anderen Organisation gehörende ids liefern 404 not_found. Erfordert den models.write Scope.

Autorisierungen

Authorization
string
header
erforderlich

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

Pfadparameter

model_id
string<uuid>
erforderlich

Body

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
Beispiel:

"Renamed Model"

default_prompt
string

New default prompt / capability description.

Maximum string length: 2000
Beispiel:

"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
Beispiel:

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

Antwort

Successful Response

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

id
string<uuid>
erforderlich
name
string
erforderlich
Beispiel:

"Acme Brand Style"

status
enum<string>
erforderlich

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

Verfügbare Optionen:
pending,
processing,
completed,
failed
Beispiel:

"completed"

is_ready
boolean
erforderlich

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

Beispiel:

true

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

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

Verfügbare Optionen:
style,
object,
person,
setting
Beispiel:

"style"

thumbnail_url
string | null

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

Beispiel:

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

Beispiel:
user_instruction
string | null

Free-text guidance for how to use the model.

Beispiel:

"Use for hero banners and social posts."

default_prompt
string | null

The model's default prompt / capability description.

Beispiel:

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

trigger_words
string[]

Trigger words associated with the model.

Beispiel: