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

# Improve a prompt

> Rewrite a short prompt into a detailed prompt for an image or a video generation. Synchronous, 1 credit per call. Coming soon.

> [!NOTE]
>
> **Coming soon.** This endpoint is not enabled yet. Until it is, every authenticated
> call returns [`503 service_unavailable`](/guides/errors#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](/api-reference/prompts/overview.md) for the
idempotency rules and the order of checks.

## Example

```bash image 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" }'
```

```bash video, German output theme={null}
curl -X POST https://api.samsa.ai/public/v1/prompts/improve \
  -H "Authorization: Bearer $SAMSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a red bicycle rolling through a park", "target": "video", "language": "de" }'
```

```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
}
```

Pass `improved_prompt` as the `prompt` of
[`POST /images/generations`](/api-reference/images/generate) or
[`POST /videos/generations`](/api-reference/videos/generate).

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

```http theme={null}
HTTP/1.1 200 OK
Idempotency-Replayed: true
Content-Type: application/json

{ "improved_prompt": "A glossy red city bicycle …", "target": "image", "language": null, "credits_charged": 1 }
```

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

| Status | Code | When |
| - | - | - |
| `401` | [`invalid_api_key`](/guides/errors#invalid_api_key) / `invalid_token` | Missing, unknown, expired, or revoked API key (`invalid_api_key`) or OAuth access token (`invalid_token`). |
| `402` | [`insufficient_credits`](/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/guides/errors#insufficient_unallocated_credits) | The balance this credential can spend is below 1 credit. Nothing is charged and the model does not run. Organizations with at least one active team get the team-aware codes (budget-exempt system organizations excepted). |
| `402` | [`subscription_inactive`](/guides/errors#subscription_inactive) | The organization has no usable subscription. |
| `403` | [`missing_scope`](/guides/errors#missing_scope) | The credential has none of `images.generate`, `images.edit`, `videos.generate`. |
| `409` | [`idempotency_key_reused`](/guides/errors#idempotency_key_reused) | The `Idempotency-Key` was already used with a different body. |
| `409` | [`idempotency_in_progress`](/guides/errors#idempotency_in_progress) | A call with this `Idempotency-Key` is still running. |
| `422` | [`validation_error`](/guides/errors#validation_error) | `prompt` is shorter than 3 or longer than 5000 characters or breaks a prompt rule, `target` is not `image` or `video`, `language` is not a valid language tag, or the `Idempotency-Key` header is invalid. |
| `429` | [`rate_limited`](/guides/errors#rate_limited) | Per-key rate window exceeded. |
| `500` | [`refund_pending`](/guides/errors#refund_pending) | The provider failed and the refund could not be confirmed yet. Samsa retries it automatically. |
| `502` | [`provider_error`](/guides/errors#provider_error) | The AI provider failed. The credit was refunded. |
| `503` | [`service_unavailable`](/guides/errors#service_unavailable) | Prompt improvement is not enabled yet (today, every call). From launch: Samsa could not confirm the idempotency state or the billing outcome. No prompt was delivered, and a credit taken is refunded automatically. |

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.


## OpenAPI

````yaml api-reference/openapi.json POST /prompts/improve
openapi: 3.1.0
info:
  title: Samsa API
  description: >-
    The Samsa public REST API. Authenticate with an organization API key
    (`Authorization: Bearer samsa_sk_...`) or an OAuth 2.1 access token
    (`Authorization: Bearer samsa_at_...`). Errors follow a single envelope
    shape; every response carries an `X-Request-ID`.
  version: 1.0.0
servers:
  - url: https://api.samsa.ai/public/v1
security:
  - BearerAuth: []
paths:
  /prompts/improve:
    post:
      tags:
        - Prompts
      summary: Improve a prompt for an image or a video generation (1 credit)
      description: >-
        Rewrites ONE prompt into a detailed, generation-ready prompt — the same
        prompt improver as the Samsa app. `target` is `image` or `video`;
        `language` (optional, BCP-47 such as `en`, `de`, `fr`) sets the language
        of the improved prompt, otherwise it keeps the language of the input.
        **Cost: 1 credit per improved prompt**, charged before the AI call; when
        the AI provider fails the credit is refunded and the call answers `502
        provider_error`. Send an `Idempotency-Key` header (1-255 printable ASCII
        characters) to retry safely: the same key with the same body within 24
        hours returns the same result with `Idempotency-Replayed: true` and is
        never charged twice (a key that ended in an error replays that error —
        use a new key for a new attempt); the same key with another body is `409
        idempotency_key_reused`; while the first request runs it is `409
        idempotency_in_progress`. Keys are scoped to the key's creator in its
        organization. Common errors: `402` (no credits or no usable subscription
        — nothing is charged), `422` (validation), `429` (rate limit). Requires
        any one of the `images.generate`, `images.edit` or `videos.generate`
        scopes. Not available yet: the endpoint answers `503
        service_unavailable` until it is enabled.
      operationId: improve_prompt_prompts_improve_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: 'null'
            description: >-
              Optional. 1-255 printable ASCII characters; see the operation
              description.
            title: Idempotency-Key
          description: >-
            Optional. 1-255 printable ASCII characters; see the operation
            description.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPromptImproveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPromptImproveResponse'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Insufficient credits or inactive subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: The API key lacks the required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >-
            `idempotency_key_reused` (the key was used with another body) or
            `idempotency_in_progress` (a request with the key is still running —
            retry).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Request validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            `refund_pending`: the AI provider failed and the refund of the
            credit is not confirmed yet (it is retried automatically), or
            `internal_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: >-
            `provider_error`: the AI provider failed; the 1 credit charged was
            refunded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: >-
            `service_unavailable`: idempotent requests or the billing outcome
            could not be confirmed (no prompt was delivered; a credit taken is
            refunded automatically).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    PublicPromptImproveRequest:
      properties:
        prompt:
          type: string
          title: Prompt
          description: >-
            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:
          type: string
          enum:
            - image
            - video
          title: Target
          description: >-
            What the improved prompt is for: `image` (text-to-image) or `video`
            (text-to-video).
        language:
          anyOf:
            - type: string
              maxLength: 63
            - type: 'null'
          title: Language
          description: >-
            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.
          examples:
            - de
      type: object
      required:
        - prompt
        - target
      title: PublicPromptImproveRequest
      description: >-
        `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.
      examples:
        - prompt: a red fox in the snow at dawn
          target: image
        - language: de
          prompt: Ein Fuchs läuft durch den Schnee
          target: video
    PublicPromptImproveResponse:
      properties:
        improved_prompt:
          type: string
          title: Improved Prompt
          description: The improved prompt.
        target:
          type: string
          enum:
            - image
            - video
          title: Target
          description: The `target` of the request.
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: >-
            The requested language tag (canonical BCP-47 form), or `null` when
            none was requested.
        credits_charged:
          type: integer
          title: Credits Charged
          description: >-
            Credits charged for this improved prompt (always 1; a replayed
            idempotent call reports the charge of its key — it is never charged
            twice).
      type: object
      required:
        - improved_prompt
        - target
        - language
        - credits_charged
      title: PublicPromptImproveResponse
      description: '`POST /prompts/improve` 200 body.'
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorEnvelope
      description: The complete public error body — an ``error`` object wrapper (ADR §5).
    ErrorDetail:
      properties:
        type:
          type: string
          title: Type
          examples:
            - authentication_error
        code:
          type: string
          title: Code
          examples:
            - invalid_api_key
        message:
          type: string
          title: Message
          examples:
            - The provided API key is invalid, expired, or revoked.
        request_id:
          type: string
          title: Request Id
          examples:
            - 8f14e45fceea167a5a36dedd4bea2543
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
          description: Present on validation errors — names the offending field.
          examples:
            - aspect_ratio
      type: object
      required:
        - type
        - code
        - message
        - request_id
      title: ErrorDetail
      description: The ``error`` object of the public envelope (ADR §5).
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key (`Authorization: Bearer samsa_sk_...`) or OAuth 2.1
        access token (`Authorization: Bearer samsa_at_...`).

````

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