> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Improvement

> Turn a short prompt into a detailed, generation-ready prompt for an image or a video — 1 credit per call. Coming soon.

> [!NOTE]
>
> **Coming soon.** Prompt improvement is not enabled yet. Until it is,
> `POST /prompts/improve` returns
> [`503 service_unavailable`](/guides/errors#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`](/api-reference/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](/mcp-server/tools.md).

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:

```bash theme={null}
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" }'
```

```json 200 OK theme={null}
{
  "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`](/api-reference/images/generate) (or of the MCP tool
`generate_image`). For `target: "video"`, send it to
[`POST /videos/generations`](/api-reference/videos/generate).

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

1. **Authentication** — `401` (`invalid_api_key`, or `invalid_token` for an OAuth
   access token).
2. **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.
3. **Rate limit** — `429 rate_limited`.
4. **Scope** — `403 missing_scope`.
5. **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](/guides/pricing.md#when-you-run-out-of-credits).
* If the AI provider fails, the credit is **refunded automatically** and the call
  returns [`502 provider_error`](/guides/errors#provider_error).
* In the rare case that the refund cannot be confirmed at once, the call returns
  [`500 refund_pending`](/guides/errors#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`](/guides/errors#idempotency_key_reused). Nothing is charged. |
| Same key, first call still running | [`409 idempotency_in_progress`](/guides/errors#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`](/guides/errors#missing_scope).

## Rate limits

Each enabled call counts against the key's
[per-key request rate](/guides/rate-limits.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.