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

# Améliorer un prompt

> Réécris un prompt court en un prompt détaillé pour la génération d'une image ou d'une vidéo. Synchrone, 1 credit par appel. Bientôt disponible.

> [!NOTE]
>
> **Bientôt disponible.** Cet endpoint n'est pas encore activé. D'ici là, chaque appel
> authentifié renvoie
> [`503 service_unavailable`](/fr/guides/errors#service_unavailable) avec le message
> `Prompt improvement is not available yet.` Rien n'est facturé, et l'appel ne compte
> pas dans ta rate limit. Le comportement ci-dessous s'applique dès le lancement.

Améliore un `prompt` pour un `target` `image` ou `video`. L'appel est **synchrone**
et renvoie **`200 OK`** avec le `improved_prompt`. Il coûte **1 credit**, débité
avant que le modèle d'IA ne tourne et remboursé automatiquement si le fournisseur
échoue. Nécessite **l'un** des scopes `images.generate`, `images.edit` ou
`videos.generate`. Les règles d'idempotence et l'ordre des
vérifications sont décrits dans l'[aperçu](/fr/api-reference/prompts/overview.md).

## Exemple

```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 vidéo, sortie en allemand 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
}
```

Passe `improved_prompt` comme `prompt` à
[`POST /images/generations`](/fr/api-reference/images/generate) ou à
[`POST /videos/generations`](/fr/api-reference/videos/generate).

## Réessayer avec un `Idempotency-Key`

Si tu répètes l'appel avec le **même** `Idempotency-Key` et le **même** body dans les
24 heures, tu récupères le résultat enregistré — sans second débit. La répétition
porte le 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` indique le débit de l'appel d'origine ; la répétition elle-même ne
coûte rien. Sans le header, chaque appel est un nouveau débit. Une clé dont le premier
appel a échoué renvoie cette erreur : utilise une nouvelle clé pour une nouvelle
tentative payante.

## Erreurs

Tant que l'endpoint n'est pas activé, un appel authentifié renvoie uniquement
`503 service_unavailable`. Dès le lancement, l'appel peut renvoyer :

| Statut | Code | Quand |
| - | - | - |
| `401` | [`invalid_api_key`](/fr/guides/errors#invalid_api_key) / `invalid_token` | Clé API (`invalid_api_key`) ou access token OAuth (`invalid_token`) manquant, inconnu, expiré ou révoqué. |
| `402` | [`insufficient_credits`](/fr/guides/errors#insufficient_credits) / [`insufficient_team_credits`](/fr/guides/errors#insufficient_team_credits) / [`insufficient_unallocated_credits`](/fr/guides/errors#insufficient_unallocated_credits) | Le solde que ces identifiants peuvent dépenser est inférieur à 1 credit. Rien n'est facturé et le modèle ne tourne pas. Les organisations avec au moins une équipe active reçoivent les codes liés aux équipes (sauf les organisations système exemptées de budget). |
| `402` | [`subscription_inactive`](/fr/guides/errors#subscription_inactive) | L'organisation n'a aucun abonnement utilisable. |
| `403` | [`missing_scope`](/fr/guides/errors#missing_scope) | Les identifiants n'ont aucun de `images.generate`, `images.edit`, `videos.generate`. |
| `409` | [`idempotency_key_reused`](/fr/guides/errors#idempotency_key_reused) | L'`Idempotency-Key` a déjà été utilisé avec un body différent. |
| `409` | [`idempotency_in_progress`](/fr/guides/errors#idempotency_in_progress) | Un appel avec cet `Idempotency-Key` est encore en cours. |
| `422` | [`validation_error`](/fr/guides/errors#validation_error) | `prompt` fait moins de 3 ou plus de 5000 caractères ou enfreint une règle de prompt, `target` n'est ni `image` ni `video`, `language` n'est pas un tag de langue valide, ou le header `Idempotency-Key` est invalide. |
| `429` | [`rate_limited`](/fr/guides/errors#rate_limited) | Fenêtre de rate par clé dépassée. |
| `500` | [`refund_pending`](/fr/guides/errors#refund_pending) | Le fournisseur a échoué et le remboursement n'a pas encore pu être confirmé. Samsa le relance automatiquement. |
| `502` | [`provider_error`](/fr/guides/errors#provider_error) | Le fournisseur d'IA a échoué. Le credit a été remboursé. |
| `503` | [`service_unavailable`](/fr/guides/errors#service_unavailable) | L'amélioration de prompts n'est pas encore activée (aujourd'hui, à chaque appel). Dès le lancement : Samsa n'a pas pu confirmer l'état d'idempotence ou le résultat de la facturation. Aucun prompt n'a été livré, et un credit débité est remboursé automatiquement. |

Un `Idempotency-Key` répété dont le premier appel a échoué renvoie la même erreur, avec
`Idempotency-Replayed: true`. Le header de réponse `X-Request-ID` identifie l'appel
pour le 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.