Passer au contenu principal
POST
Improve a prompt for an image or a video generation (1 credit)
Bientôt disponible. Cet endpoint n’est pas encore activé. D’ici là, chaque appel authentifié renvoie 503 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.

Exemple

200 OK
Passe improved_prompt comme prompt à POST /images/generations ou à POST /videos/generations.

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

Autorisations

Authorization
string
header
requis

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

En-têtes

Idempotency-Key
string | null

Optional. 1-255 printable ASCII characters; see the operation description.

Maximum string length: 255

Corps

application/json

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.

prompt
string
requis

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
enum<string>
requis

What the improved prompt is for: image (text-to-image) or video (text-to-video).

Options disponibles:
image,
video
language
string | null

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.

Maximum string length: 63
Exemple:

"de"

Réponse

Successful Response

POST /prompts/improve 200 body.

improved_prompt
string
requis

The improved prompt.

target
enum<string>
requis

The target of the request.

Options disponibles:
image,
video
language
string | null
requis

The requested language tag (canonical BCP-47 form), or null when none was requested.

credits_charged
integer
requis

Credits charged for this improved prompt (always 1; a replayed idempotent call reports the charge of its key — it is never charged twice).