Vai al contenuto principale
POST
Improve a prompt for an image or a video generation (1 credit)
In arrivo. Questo endpoint non è ancora attivato. Fino ad allora, ogni chiamata autenticata restituisce 503 service_unavailable con il messaggio Prompt improvement is not available yet. Non viene addebitato nulla, e la chiamata non conta nel tuo rate limit. Il comportamento descritto qui sotto vale dal lancio.
Migliora un prompt per un target image o video. La chiamata è sincrona e restituisce 200 OK con il improved_prompt. Costa 1 credit, addebitato prima che il modello di IA venga eseguito e rimborsato automaticamente se il provider fallisce. Richiede uno qualsiasi degli scope images.generate, images.edit o videos.generate. Le regole di idempotenza e l’ordine dei controlli sono nella panoramica.

Esempio

200 OK
Passa improved_prompt come prompt a POST /images/generations o a POST /videos/generations.

Ripetere con un Idempotency-Key

Se ripeti la chiamata con lo stesso Idempotency-Key e lo stesso body entro 24 ore, ricevi il risultato salvato — senza un secondo addebito. La ripetizione porta l’header Idempotency-Replayed: true:
credits_charged riporta l’addebito della chiamata originale; la ripetizione in sé non costa nulla. Senza l’header, ogni chiamata è un nuovo addebito. Una chiave la cui prima chiamata è fallita restituisce di nuovo quell’errore: usa una nuova chiave per un nuovo tentativo a pagamento.

Errori

Finché l’endpoint non è attivato, una chiamata autenticata restituisce solo 503 service_unavailable. Dal lancio, la chiamata può restituire: Un Idempotency-Key ripetuto la cui prima chiamata è fallita restituisce di nuovo lo stesso errore, con Idempotency-Replayed: true. L’header di risposta X-Request-ID identifica la chiamata per il supporto.

Autorizzazioni

Authorization
string
header
obbligatorio

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

Intestazioni

Idempotency-Key
string | null

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

Maximum string length: 255

Corpo

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
obbligatorio

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

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

Opzioni disponibili:
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
Esempio:

"de"

Risposta

Successful Response

POST /prompts/improve 200 body.

improved_prompt
string
obbligatorio

The improved prompt.

target
enum<string>
obbligatorio

The target of the request.

Opzioni disponibili:
image,
video
language
string | null
obbligatorio

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

credits_charged
integer
obbligatorio

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