Amélioration de prompts

Bientôt disponible. L’amélioration de prompts n’est pas encore activée. D’ici là, POST /prompts/improve renvoie 503 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 — 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.

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 :

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" }'

200 OK

{
  "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 (ou à l’outil MCP generate_image). Pour target: "video", envoie-le à POST /videos/generations.

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 :

Authentification — 401 (invalid_api_key, ou invalid_token pour un access token OAuth).
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.
Rate limit — 429 rate_limited.
Scope — 403 missing_scope.
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.
Si le fournisseur d’IA échoue, le credit est remboursé automatiquement et l’appel renvoie 502 provider_error.
Dans le cas rare où le remboursement ne peut pas être confirmé tout de suite, l’appel renvoie 500 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`. Rien n’est facturé.
Même clé, premier appel encore en cours	`409 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.

Rate limits

Chaque appel activé compte dans le 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.

Vue d'ensemble

Points de terminaison

Amélioration de prompts

Exemple : améliorer, puis générer

Requête

Ordre des vérifications

Credits

Idempotence

Scope

Rate limits

​Exemple : améliorer, puis générer

​Requête

​Ordre des vérifications

​Credits

​Idempotence

​Scope

​Rate limits

Exemple : améliorer, puis générer

Requête

Ordre des vérifications

Credits

Idempotence

Scope

Rate limits