curl --request POST \
--url https://api.samsa.ai/public/v1/prompts/improve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
'import requests
url = "https://api.samsa.ai/public/v1/prompts/improve"
payload = {
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'a red fox in the snow at dawn', target: 'image'})
};
fetch('https://api.samsa.ai/public/v1/prompts/improve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/prompts/improve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'a red fox in the snow at dawn',
'target' => 'image'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/prompts/improve"
payload := strings.NewReader("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/prompts/improve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/prompts/improve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}"
response = http.request(request)
puts response.read_body{
"improved_prompt": "<string>",
"target": "image",
"language": "<string>",
"credits_charged": 123
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}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.
curl --request POST \
--url https://api.samsa.ai/public/v1/prompts/improve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
'import requests
url = "https://api.samsa.ai/public/v1/prompts/improve"
payload = {
"prompt": "a red fox in the snow at dawn",
"target": "image"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'a red fox in the snow at dawn', target: 'image'})
};
fetch('https://api.samsa.ai/public/v1/prompts/improve', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samsa.ai/public/v1/prompts/improve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'a red fox in the snow at dawn',
'target' => 'image'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.samsa.ai/public/v1/prompts/improve"
payload := strings.NewReader("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.samsa.ai/public/v1/prompts/improve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.samsa.ai/public/v1/prompts/improve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"a red fox in the snow at dawn\",\n \"target\": \"image\"\n}"
response = http.request(request)
puts response.read_body{
"improved_prompt": "<string>",
"target": "image",
"language": "<string>",
"credits_charged": 123
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid, expired, or revoked.",
"request_id": "8f14e45fceea167a5a36dedd4bea2543",
"param": "aspect_ratio"
}
}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.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
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" }'
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" }'
{
"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
}
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 :
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 uniquement503 service_unavailable. Dès le lancement, l’appel peut renvoyer :
| Statut | Code | Quand |
|---|---|---|
401 | 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 / insufficient_team_credits / 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 | L’organisation n’a aucun abonnement utilisable. |
403 | missing_scope | Les identifiants n’ont aucun de images.generate, images.edit, videos.generate. |
409 | idempotency_key_reused | L’Idempotency-Key a déjà été utilisé avec un body différent. |
409 | idempotency_in_progress | Un appel avec cet Idempotency-Key est encore en cours. |
422 | 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 | Fenêtre de rate par clé dépassée. |
500 | refund_pending | Le fournisseur a échoué et le remboursement n’a pas encore pu être confirmé. Samsa le relance automatiquement. |
502 | provider_error | Le fournisseur d’IA a échoué. Le credit a été remboursé. |
503 | 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. |
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
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
En-têtes
Optional. 1-255 printable ASCII characters; see the operation description.
255Corps
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.
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).
What the improved prompt is for: image (text-to-image) or video (text-to-video).
image, video 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.
63"de"
Réponse
Successful Response
POST /prompts/improve 200 body.
The improved prompt.
The target of the request.
image, video The requested language tag (canonical BCP-47 form), or null when none was requested.
Credits charged for this improved prompt (always 1; a replayed idempotent call reports the charge of its key — it is never charged twice).