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

# Einen Prompt verbessern

> Schreib einen kurzen Prompt in einen detaillierten Prompt für eine Bild- oder Videogenerierung um. Synchron, 1 Credit pro Aufruf. Demnächst verfügbar.

> [!NOTE]
>
> **Demnächst verfügbar.** Dieser Endpunkt ist noch nicht aktiviert. Bis dahin gibt
> jeder authentifizierte Aufruf
> [`503 service_unavailable`](/de/guides/errors#service_unavailable) mit der Meldung
> `Prompt improvement is not available yet.` zurück. Es wird nichts berechnet, und
> der Aufruf zählt nicht gegen dein Rate Limit. Das Verhalten unten gilt ab dem
> Start.

Verbessere einen `prompt` für ein `target` `image` oder `video`. Der Aufruf ist
**synchron** und gibt **`200 OK`** mit dem `improved_prompt` zurück. Er kostet
**1 Credit**, der vor dem Lauf des KI-Modells abgebucht und bei einem Fehler des
Providers automatisch erstattet wird. Erfordert **einen** der Scopes
`images.generate`, `images.edit` oder `videos.generate`. Die Regeln zur Idempotenz
und die Reihenfolge der Prüfungen findest du in der
[Übersicht](/de/api-reference/prompts/overview.md).

## Beispiel

```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, deutsche Ausgabe 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
}
```

Gib `improved_prompt` als `prompt` an
[`POST /images/generations`](/de/api-reference/images/generate) oder
[`POST /videos/generations`](/de/api-reference/videos/generate) weiter.

## Wiederholen mit einem `Idempotency-Key`

Wiederholst du den Aufruf mit **demselben** `Idempotency-Key` und **demselben** Body
innerhalb von 24 Stunden, erhältst du das gespeicherte Ergebnis zurück — ohne zweite
Abbuchung. Die Wiederholung trägt den 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` meldet die Abbuchung des ursprünglichen Aufrufs; die Wiederholung
selbst kostet nichts. Ohne den Header ist jeder Aufruf eine neue Abbuchung. Ein Key,
dessen erster Aufruf fehlgeschlagen ist, gibt diesen Fehler erneut zurück — verwende
für einen neuen bezahlten Versuch einen neuen Key.

## Fehler

Solange der Endpunkt nicht aktiviert ist, gibt ein authentifizierter Aufruf nur
`503 service_unavailable` zurück. Ab dem Start kann der Aufruf Folgendes
zurückgeben:

| Status | Code | Wann |
| - | - | - |
| `401` | [`invalid_api_key`](/de/guides/errors#invalid_api_key) / `invalid_token` | Fehlender, unbekannter, abgelaufener oder widerrufener API-Key (`invalid_api_key`) oder OAuth-Access-Token (`invalid_token`). |
| `402` | [`insufficient_credits`](/de/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/de/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/de/guides/errors#insufficient_unallocated_credits) | Der Stand, den diese Zugangsdaten ausgeben können, liegt unter 1 Credit. Es wird nichts berechnet und das Modell läuft nicht. Organisationen mit mindestens einem aktiven Team erhalten die teambezogenen Codes (budgetbefreite System-Organisationen ausgenommen). |
| `402` | [`subscription_inactive`](/de/guides/errors#subscription_inactive) | Die Organisation hat kein nutzbares Abonnement. |
| `403` | [`missing_scope`](/de/guides/errors#missing_scope) | Die Zugangsdaten haben keinen von `images.generate`, `images.edit`, `videos.generate`. |
| `409` | [`idempotency_key_reused`](/de/guides/errors#idempotency_key_reused) | Der `Idempotency-Key` wurde bereits mit einem anderen Body verwendet. |
| `409` | [`idempotency_in_progress`](/de/guides/errors#idempotency_in_progress) | Ein Aufruf mit diesem `Idempotency-Key` läuft noch. |
| `422` | [`validation_error`](/de/guides/errors#validation_error) | `prompt` ist kürzer als 3 oder länger als 5000 Zeichen oder verletzt eine Prompt-Regel, `target` ist nicht `image` oder `video`, `language` ist kein gültiges Sprach-Tag, oder der `Idempotency-Key`-Header ist ungültig. |
| `429` | [`rate_limited`](/de/guides/errors#rate_limited) | Rate-Fenster pro Key überschritten. |
| `500` | [`refund_pending`](/de/guides/errors#refund_pending) | Der Provider ist fehlgeschlagen und die Erstattung konnte noch nicht bestätigt werden. Samsa wiederholt sie automatisch. |
| `502` | [`provider_error`](/de/guides/errors#provider_error) | Der KI-Provider ist fehlgeschlagen. Der Credit wurde erstattet. |
| `503` | [`service_unavailable`](/de/guides/errors#service_unavailable) | Die Prompt-Verbesserung ist noch nicht aktiviert (heute bei jedem Aufruf). Ab dem Start: Samsa konnte den Idempotenz-Zustand oder das Abrechnungsergebnis nicht bestätigen. Es wurde kein Prompt geliefert, und ein abgebuchter Credit wird automatisch erstattet. |

Ein wiederholter `Idempotency-Key`, dessen erster Aufruf fehlgeschlagen ist, gibt
denselben Fehler erneut zurück, mit `Idempotency-Replayed: true`. Der
Response-Header `X-Request-ID` identifiziert den Aufruf für den 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.