Skip to main content
POST
Improve a prompt for an image or a video generation (1 credit)
Coming soon. This endpoint is not enabled yet. Until it is, every authenticated call returns 503 service_unavailable with the message Prompt improvement is not available yet. Nothing is charged, and the call does not count against your rate limit. The behaviour below applies from launch.
Improve one prompt for a target of image or video. The call is synchronous and returns 200 OK with the improved_prompt. It costs 1 credit, charged before the AI model runs and refunded automatically if the provider fails. Requires any one of the images.generate, images.edit, or videos.generate scopes. See the overview for the idempotency rules and the order of checks.

Example

200 OK
Pass improved_prompt as the prompt of POST /images/generations or POST /videos/generations.

Retrying with an Idempotency-Key

Repeat the call with the same Idempotency-Key and the same body within 24 hours, and you get the stored result back — with no second charge. The replay carries the header Idempotency-Replayed: true:
credits_charged reports the charge of the original call; the replay itself costs nothing. Without the header, every call is a new charge. A key whose first call failed replays that error, so use a new key for a new paid attempt.

Errors

Today, while the endpoint is not enabled, an authenticated call returns only 503 service_unavailable. From launch, the call can return: A replayed Idempotency-Key whose first call failed returns that same error again, with Idempotency-Replayed: true. The X-Request-ID response header identifies the call for support.

Authorizations

Authorization
string
header
required

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

Headers

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
required

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

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

Available options:
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
Example:

"de"

Response

Successful Response

POST /prompts/improve 200 body.

improved_prompt
string
required

The improved prompt.

target
enum<string>
required

The target of the request.

Available options:
image,
video
language
string | null
required

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

credits_charged
integer
required

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