Prompt Improvement

Coming soon. Prompt improvement is not enabled yet. Until it is, POST /prompts/improve returns 503 service_unavailable with the message Prompt improvement is not available yet., and the MCP tool improve_prompt does not appear in the server’s tool list. Nothing is charged, and a disabled call does not count against your rate limit. The credits, idempotency, and error behaviour on this page apply from launch.

The prompt improver rewrites a short prompt into a detailed one that is ready for an image or a video generation.

POST /prompts/improve — improve one prompt for target image or video.
The MCP server will have the same operation as the tool improve_prompt — see MCP tools.

The call is synchronous: the 200 response contains the improved prompt. There is no job to poll and no webhook.

Example: improve, then generate

Improve a red bicycle in a park for an image:

curl -X POST https://api.samsa.ai/public/v1/prompts/improve \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a3e-improve-bicycle" \
  -d '{ "prompt": "a red bicycle in a park", "target": "image" }'

200 OK

{
  "improved_prompt": "A glossy red city bicycle leaning against a wooden bench in a sunlit park, autumn leaves on the path, soft morning light, shallow depth of field, photorealistic",
  "target": "image",
  "language": null,
  "credits_charged": 1
}

Then send improved_prompt as the prompt of POST /images/generations (or of the MCP tool generate_image). For target: "video", send it to POST /videos/generations.

Request

Field	Required	Description
`prompt`	Yes	The prompt to improve: 3 to 5000 characters after trimming. The same rules as every Samsa prompt apply: no `<` or `>`, no backslashes, no line breaks or tabs. A prompt that breaks a rule returns `422`.
`target`	Yes	`image` (text-to-image) or `video` (text-to-video). The improver writes for that medium.
`language`	No	The language of the improved prompt, as a BCP-47 language tag such as `en`, `de`, or `fr`. If you omit it, the improved prompt keeps the language of your prompt.

Unknown body fields are ignored. The 200 response has four fields:

Field	Description
`improved_prompt`	The improved prompt.
`target`	The `target` of your request.
`language`	The language tag you sent, in canonical BCP-47 form, or `null` when you sent none.
`credits_charged`	The credits charged for this call: always `1`. A replay reports the charge of the original call.

Every response carries an X-Request-ID header. Quote it when you contact support.

Order of checks

A call is checked in this order. The first check that fails decides the response:

Authentication — 401 (invalid_api_key, or invalid_token for an OAuth access token).
Availability — 503 service_unavailable while prompt improvement is not enabled. This check runs before the rate limiter, so a disabled call does not count against your rate limit.
Rate limit — 429 rate_limited.
Scope — 403 missing_scope.
Validation — 422 validation_error.

Credits

From launch, each call costs 1 credit. The credit is charged before the AI model runs:

If the balance this credential can spend is too low, the call returns 402 — nothing is charged and the model does not run. See When you run out of credits.
If the AI provider fails, the credit is refunded automatically and the call returns 502 provider_error.
In the rare case that the refund cannot be confirmed at once, the call returns 500 refund_pending. Samsa retries the refund automatically — you do not need to do anything.

Idempotency

Send an optional Idempotency-Key header (1–255 printable ASCII characters, for example a UUID) to retry safely after a timeout or a network error:

Situation	Result
Same key, same body, within 24 hours	The same result as the first call, with the response header `Idempotency-Replayed: true`. Never a second charge.
Same key, first call failed	The same error again, with `Idempotency-Replayed: true`. For a new paid attempt, use a new key.
Same key, different body	`409 idempotency_key_reused`. Nothing is charged.
Same key, first call still running	`409 idempotency_in_progress`. Retry after a few seconds.
No `Idempotency-Key` header	Every call is a new call and a new charge.

Keys are scoped to the owner of the credential — the API key’s creator or the OAuth user — within the organization. REST calls, MCP calls, and all credentials of the same owner share one key namespace. Two different users can use the same key value without a conflict.

Scope

A credential with any one of the images.generate, images.edit, or videos.generate scopes can call the improver — the scopes of the operations an improved prompt is for. There is no separate scope, so existing keys work. A key with none of the three gets 403 missing_scope.

Rate limits

Each enabled call counts against the key’s per-key request rate (429 rate_limited with Retry-After). The call creates no job, so it does not use the organization’s concurrency cap.

Overview

Endpoints

Prompt Improvement

Example: improve, then generate

Request

Order of checks

Credits

Idempotency

Scope

Rate limits

​Example: improve, then generate

​Request

​Order of checks

​Credits

​Idempotency

​Scope

​Rate limits

Example: improve, then generate

Request

Order of checks

Credits

Idempotency

Scope

Rate limits