Zum Hauptinhalt springen
POST
Improve a prompt for an image or a video generation (1 credit)
Demnächst verfügbar. Dieser Endpunkt ist noch nicht aktiviert. Bis dahin gibt jeder authentifizierte Aufruf 503 service_unavailable mit der Meldung Prompt improvement is not available yet. zurück. Es wird nichts berechnet, und der Aufruf zählt nicht gegen dein Rate Limit. Das Verhalten unten gilt ab dem Start.
Verbessere einen prompt für ein target image oder video. Der Aufruf ist synchron und gibt 200 OK mit dem improved_prompt zurück. Er kostet 1 Credit, der vor dem Lauf des KI-Modells abgebucht und bei einem Fehler des Providers automatisch erstattet wird. Erfordert einen der Scopes images.generate, images.edit oder videos.generate. Die Regeln zur Idempotenz und die Reihenfolge der Prüfungen findest du in der Übersicht.

Beispiel

200 OK
Gib improved_prompt als prompt an POST /images/generations oder POST /videos/generations weiter.

Wiederholen mit einem Idempotency-Key

Wiederholst du den Aufruf mit demselben Idempotency-Key und demselben Body innerhalb von 24 Stunden, erhältst du das gespeicherte Ergebnis zurück — ohne zweite Abbuchung. Die Wiederholung trägt den Header Idempotency-Replayed: true:
credits_charged meldet die Abbuchung des ursprünglichen Aufrufs; die Wiederholung selbst kostet nichts. Ohne den Header ist jeder Aufruf eine neue Abbuchung. Ein Key, dessen erster Aufruf fehlgeschlagen ist, gibt diesen Fehler erneut zurück — verwende für einen neuen bezahlten Versuch einen neuen Key.

Fehler

Solange der Endpunkt nicht aktiviert ist, gibt ein authentifizierter Aufruf nur 503 service_unavailable zurück. Ab dem Start kann der Aufruf Folgendes zurückgeben: Ein wiederholter Idempotency-Key, dessen erster Aufruf fehlgeschlagen ist, gibt denselben Fehler erneut zurück, mit Idempotency-Replayed: true. Der Response-Header X-Request-ID identifiziert den Aufruf für den Support.

Autorisierungen

Authorization
string
header
erforderlich

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Header

Idempotency-Key
string | null

Optional. 1-255 printable ASCII characters; see the operation description.

Maximum string length: 255

Body

application/json

POST /prompts/improve body — improve ONE prompt for an image or a video generation.

Cost = 1 credit per improved prompt, charged before the AI call and refunded automatically when the AI provider fails (502 provider_error). Send an Idempotency-Key header to retry safely: the same key with the same body within 24 hours returns the same result and never charges twice.

prompt
string
erforderlich

The prompt to improve: 3 to 5000 characters after trimming (the characters < and >, line breaks and backslashes are not allowed — the same rules as every Samsa prompt).

target
enum<string>
erforderlich

What the improved prompt is for: image (text-to-image) or video (text-to-video).

Verfügbare Optionen:
image,
video
language
string | null

Optional BCP-47 / ISO 639-1 language tag of the improved prompt (e.g. en, de, fr). Omitted: the improved prompt keeps the language of the input prompt.

Maximum string length: 63
Beispiel:

"de"

Antwort

Successful Response

POST /prompts/improve 200 body.

improved_prompt
string
erforderlich

The improved prompt.

target
enum<string>
erforderlich

The target of the request.

Verfügbare Optionen:
image,
video
language
string | null
erforderlich

The requested language tag (canonical BCP-47 form), or null when none was requested.

credits_charged
integer
erforderlich

Credits charged for this improved prompt (always 1; a replayed idempotent call reports the charge of its key — it is never charged twice).