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"
}
}Einen Prompt verbessern
Schreib einen kurzen Prompt in einen detaillierten Prompt für eine Bild- oder Videogenerierung um. Synchron, 1 Credit pro Aufruf. Demnächst verfügbar.
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 mit der Meldung
Prompt improvement is not available yet. zurück. Es wird nichts berechnet, und
der Aufruf zählt nicht gegen dein Rate Limit. Das Verhalten unten gilt ab dem
Start.prompt für ein target image oder video. Der Aufruf ist
synchron und gibt 200 OK mit dem improved_prompt zurück. Er kostet
1 Credit, der vor dem Lauf des KI-Modells abgebucht und bei einem Fehler des
Providers automatisch erstattet wird. Erfordert einen der Scopes
images.generate, images.edit oder videos.generate. Die Regeln zur Idempotenz
und die Reihenfolge der Prüfungen findest du in der
Übersicht.
Beispiel
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 als prompt an
POST /images/generations oder
POST /videos/generations weiter.
Wiederholen mit einem Idempotency-Key
Wiederholst du den Aufruf mit demselben Idempotency-Key und demselben Body
innerhalb von 24 Stunden, erhältst du das gespeicherte Ergebnis zurück — ohne zweite
Abbuchung. Die Wiederholung trägt den 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 meldet die Abbuchung des ursprünglichen Aufrufs; die Wiederholung
selbst kostet nichts. Ohne den Header ist jeder Aufruf eine neue Abbuchung. Ein Key,
dessen erster Aufruf fehlgeschlagen ist, gibt diesen Fehler erneut zurück — verwende
für einen neuen bezahlten Versuch einen neuen Key.
Fehler
Solange der Endpunkt nicht aktiviert ist, gibt ein authentifizierter Aufruf nur503 service_unavailable zurück. Ab dem Start kann der Aufruf Folgendes
zurückgeben:
| Status | Code | Wann |
|---|---|---|
401 | invalid_api_key / invalid_token | Fehlender, unbekannter, abgelaufener oder widerrufener API-Key (invalid_api_key) oder OAuth-Access-Token (invalid_token). |
402 | insufficient_credits / insufficient_team_credits / insufficient_unallocated_credits | Der Stand, den diese Zugangsdaten ausgeben können, liegt unter 1 Credit. Es wird nichts berechnet und das Modell läuft nicht. Organisationen mit mindestens einem aktiven Team erhalten die teambezogenen Codes (budgetbefreite System-Organisationen ausgenommen). |
402 | subscription_inactive | Die Organisation hat kein nutzbares Abonnement. |
403 | missing_scope | Die Zugangsdaten haben keinen von images.generate, images.edit, videos.generate. |
409 | idempotency_key_reused | Der Idempotency-Key wurde bereits mit einem anderen Body verwendet. |
409 | idempotency_in_progress | Ein Aufruf mit diesem Idempotency-Key läuft noch. |
422 | validation_error | prompt ist kürzer als 3 oder länger als 5000 Zeichen oder verletzt eine Prompt-Regel, target ist nicht image oder video, language ist kein gültiges Sprach-Tag, oder der Idempotency-Key-Header ist ungültig. |
429 | rate_limited | Rate-Fenster pro Key überschritten. |
500 | refund_pending | Der Provider ist fehlgeschlagen und die Erstattung konnte noch nicht bestätigt werden. Samsa wiederholt sie automatisch. |
502 | provider_error | Der KI-Provider ist fehlgeschlagen. Der Credit wurde erstattet. |
503 | service_unavailable | Die Prompt-Verbesserung ist noch nicht aktiviert (heute bei jedem Aufruf). Ab dem Start: Samsa konnte den Idempotenz-Zustand oder das Abrechnungsergebnis nicht bestätigen. Es wurde kein Prompt geliefert, und ein abgebuchter Credit wird automatisch erstattet. |
Idempotency-Key, dessen erster Aufruf fehlgeschlagen ist, gibt
denselben Fehler erneut zurück, mit Idempotency-Replayed: true. Der
Response-Header X-Request-ID identifiziert den Aufruf für den Support.Autorisierungen
Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).
Header
Optional. 1-255 printable ASCII characters; see the operation description.
255Body
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"
Antwort
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).