> ## 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élioration de prompts > Transforme un prompt court en un prompt détaillé, prêt pour la génération d'une image ou d'une vidéo — 1 credit par appel. Bientôt disponible. > [!NOTE] > > **Bientôt disponible.** L'amélioration de prompts n'est pas encore activée. D'ici là, > `POST /prompts/improve` renvoie > [`503 service_unavailable`](/fr/guides/errors#service_unavailable) avec le message > `Prompt improvement is not available yet.`, et l'outil MCP `improve_prompt` > n'apparaît pas dans la liste des outils du server. Rien n'est facturé, et un appel > désactivé ne compte pas dans ta rate limit. Le comportement des credits, de > l'idempotence et des erreurs décrit sur cette page s'applique dès le lancement. L'améliorateur de prompts réécrit un prompt court en un prompt détaillé, prêt pour la génération d'une image ou d'une vidéo. * [`POST /prompts/improve`](/fr/api-reference/prompts/improve) — améliore un prompt pour le `target` `image` ou `video`. * Le MCP server proposera la même opération avec l'outil `improve_prompt` — voir [Outils MCP](/fr/mcp-server/tools.md). L'appel est **synchrone** : la réponse `200` contient le prompt amélioré. Il n'y a aucun job à interroger et aucun webhook. ## Exemple : améliorer, puis générer Améliore `a red bicycle in a park` pour une 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 } ``` Envoie ensuite `improved_prompt` comme `prompt` à [`POST /images/generations`](/fr/api-reference/images/generate) (ou à l'outil MCP `generate_image`). Pour `target: "video"`, envoie-le à [`POST /videos/generations`](/fr/api-reference/videos/generate). ## Requête | Champ | Requis | Description | | - | - | - | | `prompt` | Oui | Le prompt à améliorer : **3 à 5000 caractères** après suppression des espaces de début et de fin. Les mêmes règles que pour tout prompt Samsa s'appliquent : pas de `<` ni de `>`, pas de barres obliques inverses, pas de sauts de ligne ni de tabulations. Un prompt qui enfreint une règle renvoie `422`. | | `target` | Oui | `image` (text-to-image) ou `video` (text-to-video). L'améliorateur écrit pour ce média. | | `language` | Non | La langue du prompt amélioré, sous forme de tag de langue BCP-47 comme `en`, `de` ou `fr`. Si tu l'omets, le prompt amélioré garde la langue de ton prompt. | Les champs inconnus du body sont ignorés. La réponse `200` contient quatre champs : | Champ | Description | | - | - | | `improved_prompt` | Le prompt amélioré. | | `target` | Le `target` de ta requête. | | `language` | Le tag de langue que tu as envoyé, sous forme BCP-47 canonique, ou `null` si tu n'en as pas envoyé. | | `credits_charged` | Les credits débités pour cet appel : toujours `1`. Une répétition indique le débit de l'appel d'origine. | Chaque réponse contient un header `X-Request-ID`. Cite-le quand tu contactes le support. ## Ordre des vérifications Un appel est vérifié dans cet ordre. La première vérification qui échoue détermine la réponse : 1. **Authentification** — `401` (`invalid_api_key`, ou `invalid_token` pour un access token OAuth). 2. **Disponibilité** — `503 service_unavailable` tant que l'amélioration de prompts n'est pas activée. Cette vérification a lieu avant le rate limiter : un appel désactivé ne compte donc pas dans ta rate limit. 3. **Rate limit** — `429 rate_limited`. 4. **Scope** — `403 missing_scope`. 5. **Validation** — `422 validation_error`. ## Credits Dès le lancement, chaque appel coûte **1 credit**. Le credit est débité **avant** que le modèle d'IA ne tourne : * Si le solde que ces identifiants peuvent dépenser est trop bas, l'appel renvoie `402` — rien n'est facturé et le modèle ne tourne pas. Voir [Quand tu es à court de credits](/fr/guides/pricing.md#quand-tu-es-à-court-de-credits). * Si le fournisseur d'IA échoue, le credit est **remboursé automatiquement** et l'appel renvoie [`502 provider_error`](/fr/guides/errors#provider_error). * Dans le cas rare où le remboursement ne peut pas être confirmé tout de suite, l'appel renvoie [`500 refund_pending`](/fr/guides/errors#refund_pending). Samsa relance le remboursement automatiquement — tu n'as rien à faire. ## Idempotence Envoie un header `Idempotency-Key` optionnel (1 à 255 caractères ASCII imprimables, par exemple un UUID) pour réessayer sans risque après un timeout ou une erreur réseau : | Situation | Résultat | | - | - | | Même clé, même body, dans les **24 heures** | Le **même résultat** que le premier appel, avec le header de réponse `Idempotency-Replayed: true`. Jamais de second débit. | | Même clé, premier appel échoué | La **même erreur** à nouveau, avec `Idempotency-Replayed: true`. Pour une nouvelle tentative payante, utilise une nouvelle clé. | | Même clé, body différent | [`409 idempotency_key_reused`](/fr/guides/errors#idempotency_key_reused). Rien n'est facturé. | | Même clé, premier appel encore en cours | [`409 idempotency_in_progress`](/fr/guides/errors#idempotency_in_progress). Réessaie après quelques secondes. | | Pas de header `Idempotency-Key` | Chaque appel est un nouvel appel et un nouveau débit. | Les clés sont propres au **titulaire** des identifiants — le créateur de la clé API ou l'utilisateur OAuth — au sein de l'organisation. Les appels REST, les appels MCP et tous les identifiants du même titulaire partagent un même espace de noms de clés. Deux utilisateurs différents peuvent utiliser la même valeur de clé sans conflit. ## Scope Des identifiants avec **l'un** des scopes `images.generate`, `images.edit` ou `videos.generate` peuvent appeler l'améliorateur — les scopes des opérations auxquelles un prompt amélioré est destiné. Il n'y a pas de scope séparé, donc les clés existantes fonctionnent. Une clé sans aucun des trois reçoit [`403 missing_scope`](/fr/guides/errors#missing_scope). ## Rate limits Chaque appel activé compte dans le [rate de requêtes par clé](/fr/guides/rate-limits.md#rate-de-requêtes-par-clé) (`429 rate_limited` avec `Retry-After`). L'appel ne crée aucun job, il n'utilise donc pas le plafond de concurrence de l'organisation. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.