Modelle und Medien

Diese Seite behandelt den Modellkatalog und alle Medien-Endpunkte. Chat-Modelle übergeben Sie als ai_model_id an Unterhaltungen und Ausführungen. Video, Sprache, Musik und Transkription haben jeweils einen eigenen Modellkatalog und folgen einem gemeinsamen Job-Muster.

Alle Pfade sind relativ zu https://api.stickyprompts.com/api/v1, und jeder Request enthält Authorization: Bearer $STICKY_API_KEY.

Konventionen

• IDs und Slugs. Jede Generierung und jede Transkription hat eine numerische ID und einen 8-stelligen slug. GET /<resource>/:id und POST /<resource>/:id/retry akzeptieren beides. DELETE /<resource>/:id akzeptiert nur die numerische ID.
• Dezimalzahlen sind Strings. Credit-Preise und Kosten (credit_cost, credit_cost_per_*, multiplier) kommen als JSON-Strings zurück, etwa "0.000015".
• Schreibweise der Felder. Datensätze enthalten ID, CreatedAt, UpdatedAt, DeletedAt in PascalCase neben Feldern in snake_case. Siehe Fehler, Paginierung und Kontingente.
• Listen sind mit page (Standard 1) und size (Standard 10) paginiert, die neuesten zuerst, mit den Headern X-Total-Count, X-Page und X-Page-Size. Der Body ist ein reines Array.
• Kontingent. Routen, die kostenpflichtige Arbeit anstoßen, antworten mit 429 {"error":"Quota exceeded","reason":"..."}, wenn der Tarif ausgeschöpft ist.
• Eingeschränkte Modelle. Blockiert eine Workspace-Regel das gewählte Modell, antworten die Aufrufe zum Anlegen mit 403 {"error":"the selected model has been restricted by your organization"}.

Chat-Modelle

Chat-Modelle werden über ihre numerische ID identifiziert. name ist ein Anzeigename, keine Kennung. Bei Zugriff per API-Schlüssel gelten die Regeln für den Modellzugriff und die Richtlinie zur Datenresidenz Ihres Workspace: Modelle, die Sie nicht verwenden dürfen, kommen mit selectable: false und einem restriction_reason zurück.

GET /ai_model

Listet den Katalog der Chat-Modelle in Anzeigereihenfolge auf. Veraltete Modelle sind enthalten, sofern Sie nicht legacy=false übergeben.

curl "https://api.stickyprompts.com/api/v1/ai_model?legacy=false&flagship=true" \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os, requests

r = requests.get(
    "https://api.stickyprompts.com/api/v1/ai_model",
    params={"legacy": "false", "flagship": "true"},
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
)
usable = [m for m in r.json() if m["selectable"]]
for m in usable:
    print(m["ID"], m["name"], m["multiplier"])

const res = await fetch(
  "https://api.stickyprompts.com/api/v1/ai_model?legacy=false&flagship=true",
  { headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` } },
);
const models = (await res.json()).filter((m) => m.selectable);
console.log(models.map((m) => [m.ID, m.name]));

Antwort 200 (ein Element gezeigt, Werte beispielhaft):

[
  {
    "ID": 42,
    "name": "Claude Sonnet 5",
    "description": "Balanced model for everyday work.",
    "powered_by": "Anthropic",
    "version": "claude-sonnet-x",
    "multiplier": "1.6",
    "credit_cost_per_input_token": "0.0003",
    "credit_cost_per_output_token": "0.0015",
    "flagship": true,
    "premium": false,
    "deprecated": false,
    "thinking_model": true,
    "reasoning_efforts": ["low", "medium", "high"],
    "default_reasoning_effort": "medium",
    "tools": ["file_upload", "web_search", "remote_mcp"],
    "tags": ["analysis", "coding"],
    "best_for": "Writing, analysis and code",
    "knowledge_cutoff": "2026-01-01T00:00:00Z",
    "supported_file_extensions": [],
    "successor": null,
    "selectable": true
  }
]

Nützliche Felder: tools listet die Fähigkeiten auf (file_upload, file_generation, image_generation, web_search, web_fetch, code_execution, remote_mcp und mehr), reasoning_efforts die erlaubten Stufen für den Denkaufwand, successor nennt den Nachfolger eines veralteten Modells, und supported_file_extensions schränkt Anhänge ein (leer bedeutet keine Einschränkung). Der Katalog enthält kein Feld für die Größe des Kontextfensters, keinen Preis in USD und keine Benchmarks.

GET /ai_model/:id

Gibt ein Modell anhand seiner numerischen ID zurück. successor wird hier nicht geladen.

GET /ai_model/filters

Gibt die verschiedenen Werte zurück, nach denen Sie den Katalog filtern können:

{
  "powered_by": ["Anthropic", "Google", "OpenAI", "xAI"],
  "tools": ["code_execution", "file_upload", "image_generation", "web_search"],
  "tags": ["analysis", "coding", "creative_writing", "reasoning"]
}

Eine Liste ist null statt [], wenn kein Modell einen Wert dafür hat.

GET /ai_model/restricted

Veraltet. Meldet nur Modelle, die in Ihrem Workspace durch eine Regel auf Modellebene blockiert sind. Verwenden Sie stattdessen das Flag selectable aus GET /ai_model.

Bildgenerierung

Die Bildgenerierung ist synchron: Der Aufruf kehrt zurück, sobald das Bild existiert. Der Server verwendet das Bildmodell, das StickyPrompts konfiguriert hat; der Prompt ist die einzige Stellschraube (es gibt keine Parameter für Größe, Anzahl oder Seitenverhältnis).

POST /image_generation

curl -X POST https://api.stickyprompts.com/api/v1/image_generation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Product photo of a laptop on an oak desk showing a retail dashboard with yellow charts, morning light"}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/image_generation",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"prompt": "Product photo of a laptop on an oak desk showing a retail dashboard"},
    timeout=180,
)
image = r.json()
print(image["ID"], image["path"])

const res = await fetch("https://api.stickyprompts.com/api/v1/image_generation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Product photo of a laptop on an oak desk showing a retail dashboard" }),
});
const image = await res.json();
console.log(image.ID, image.path);

Antwort 200, ein Dateidatensatz:

{
  "ID": 9812,
  "name": "image_0.png",
  "path": "https://<storage-host>/<bucket>/123/Xk3...q9.png",
  "user_id": 123,
  "fileType": "code_interpreter_output",
  "partial": false
}

Das Bild liegt unter path, einer direkten Speicher-URL. Merken Sie sich die ID: Sie dient als file_id zum Bearbeiten, als Startbild für ein Video und in den Datei-Endpunkten. Beachten Sie das camelCase-Feld fileType.

Fehler: 400 ohne prompt; 500 {"error":"image generation produced no output file"}, wenn das Modell nichts zurückgibt; 500 mit der Fehlermeldung, wenn das Modell fehlschlägt oder die Datenresidenz den Anbieter blockiert. Planen Sie auf Client-Seite ein großzügiges Timeout ein.

POST /image_generation/edit

Bearbeitet ein Bild, das Ihnen gehört, und gibt eine neue Datei zurück. Die Quelldatei bleibt unverändert.

Antwort 200: ein neuer Dateidatensatz. 404 {"error":"file not found or access denied"}, wenn die Datei nicht Ihnen gehört.

Hintergrund-Jobs: Video, Sprache, Musik, Transkription

Diese vier Ressourcen folgen einem gemeinsamen Muster:

1. Modell auswählen

   GET /<kind>_model gibt den Katalog der jeweiligen Art zurück. Wählen Sie ein Modell anhand seiner numerischen ID. Das Flag default: true markiert das in der App vorausgewählte Modell, die API greift aber nicht darauf zurück: Senden Sie immer die Modell-ID.

2. Job anlegen

   POST /<kind> validiert den Request, prüft Kontingent und Zugriff und antwortet mit 201 und dem Job im Status queued.

3. Abfragen, bis der Job fertig ist

   Rufen Sie GET /<kind>/:id auf, bis status den Wert done oder error hat. Für diese Jobs gibt es weder Webhooks noch Event-Streams; fragen Sie alle paar Sekunden ab.

4. Ergebnis abholen

   Video, Sprache und Musik: Die Datei liegt unter output_file_data.path. Transkription: text und segments stehen direkt im Datensatz.

import os, time, requests

API = "https://api.stickyprompts.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

job = requests.post(f"{API}/music_generation", headers=H, json={
    "music_generation_model_id": 7,          # from GET /music_generation_model
    "prompt": "Upbeat product-launch track, electric piano, 112 BPM, no vocals",
    "duration_seconds": 30,
    "instrumental": True,
}).json()

while job["status"] not in ("done", "error"):
    time.sleep(5)
    job = requests.get(f"{API}/music_generation/{job['slug']}", headers=H).json()

print(job["status"], job.get("output_file_data", {}).get("path"), job["credit_cost"])

const API = "https://api.stickyprompts.com/api/v1";
const H = { Authorization: `Bearer ${process.env.STICKY_API_KEY}`, "Content-Type": "application/json" };

let job = await (await fetch(`${API}/music_generation`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    music_generation_model_id: 7, // from GET /music_generation_model
    prompt: "Upbeat product-launch track, electric piano, 112 BPM, no vocals",
    duration_seconds: 30,
    instrumental: true,
  }),
})).json();

while (!["done", "error"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${API}/music_generation/${job.slug}`, { headers: H })).json();
}
console.log(job.status, job.output_file_data?.path, job.credit_cost);

Für alle vier gilt:

• Die Modell-ID ist Pflicht. Fehlt sie oder ist sie unbekannt, kommt ein allgemeines 500 "Failed to create ..." zurück, kein 400.
• Kosten. GET /<kind>/:id enthält credit_cost, die für den Job berechneten Credits. Listenantworten zeigen dort immer "0".
• Datenresidenz. Verbietet die Residenzrichtlinie Ihres Workspace den Anbieter des Modells, wird der Job angenommen und schlägt dann mit der Meldung der Richtlinie in error fehl. Solche Modelle zeigen im Katalog selectable: false, prüfen Sie das also vorher.
• Wiederholen. POST /<kind>/:id/retry stellt einen Job im Status error erneut in die Warteschlange (sonst 400 "Only failed ... can be retried") und prüft dabei Zugriff und Kontingent erneut.
• Löschen. DELETE /<kind>/:id (numerische ID) gibt 204 zurück, auch wenn nichts gefunden wurde. Es handelt sich um ein Soft Delete; die Ausgabedatei wird nicht entfernt.
• Listen filtern Sie mit ?status=<value>.

Jedes Medienmodell hat ID, name, powered_by, version, description, multiplier, default, sort, selectable und, falls zutreffend, restriction_reason. Die Kataloge sind nicht paginiert.

Videoerstellung

Status: queued, dann processing, dann done oder error.

GET /video_generation_model

Videomodelle haben zusätzlich: supported_aspect_ratios (leer bedeutet beliebig), supported_resolutions (die erste ist der Standard), resolution_duration_limits (pro Auflösung, "*" als Fallback, {min_duration_seconds, max_duration_seconds}, wobei 0 unbegrenzt bedeutet), resolution_pricing (credit_cost_per_second pro Auflösung), interpolation_support (none, start_only oder full), max_reference_images und reference_types.

POST /video_generation

curl -X POST https://api.stickyprompts.com/api/v1/video_generation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_generation_model_id": 4,
    "prompt": "Slow dolly shot across a bright retail store at opening time, warm morning light",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration_seconds": 8
  }'

Antwort 201 (gekürzt):

{
  "ID": 311,
  "slug": "a8Kd02Lq",
  "video_generation_model_id": 4,
  "prompt": "Slow dolly shot across a bright retail store at opening time, warm morning light",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration_seconds": 8,
  "status": "queued",
  "error": "",
  "content_policy_violation": false,
  "output_file_data_id": null,
  "credit_cost": "0"
}

Bei done ist output_file_data.path die .mp4-Datei, und actual_duration_seconds sowie credit_cost sind befüllt. content_policy_violation: true bedeutet, dass der Sicherheitsfilter des Anbieters den Request abgelehnt hat.

Validierungsfehler sind 400 mit einer präzisen Meldung, zum Beispiel "resolution is not supported by this video generation model", "requested duration exceeds this video generation model's maximum", "a last frame image requires a starting image" oder "attached file must be an image". Wenn Sie die Datei einer anderen Person verwenden, erhalten Sie 403 "you do not have permission to use this file".

GET /video_generation, GET /video_generation/:id

Listet Ihre Video-Jobs auf (page, size, status) oder ruft einen einzelnen anhand von ID oder Slug ab, einschließlich credit_cost. 404 {"error":"Video generation not found"}.

POST /video_generation/:id/retry

DELETE /video_generation/:id

Sprachausgabe

Status: queued, dann processing, dann done oder error.

GET /tts_generation_model

Sprachmodelle haben zusätzlich supported_languages (leer bedeutet beliebig) und ein tts_voice_set, dessen voices jeweils eine voice_id (der Wert, den Sie als voice senden), name, gender, language, accent, description, preview_audio_url und default haben.

POST /tts_generation

Antwortet mit 201 und dem Job. Bei done liegt das Audio (.wav oder .mp3, je nachdem, was der Anbieter geliefert hat) unter output_file_data.path. Fehler: 400 "voice is not supported by this tts generation model", 400 "language is not supported by this tts generation model".

GET /tts_generation, GET /tts_generation/:id

POST /tts_generation/:id/retry

DELETE /tts_generation/:id

Musikgenerierung

Status: queued, dann processing, dann done oder error.

GET /music_generation_model

Musikmodelle haben zusätzlich min_duration_seconds und max_duration_seconds (0 bedeutet unbegrenzt), supported_output_formats (das erste ist der Standard), credit_cost_per_generation und credit_cost_per_second.

POST /music_generation

Bei done liegt der Track unter output_file_data.path, ein eventueller Songtext steht in lyrics. Die Dateiendung richtet sich danach, was der Anbieter tatsächlich geliefert hat, und kann daher von output_format abweichen. Fehler: 400 bei einer Dauer außerhalb der Grenzen oder einem nicht unterstützten Format.

GET /music_generation, GET /music_generation/:id

POST /music_generation/:id/retry

DELETE /music_generation/:id

Transkription

Status: queued, fetching, preparing, processing, dann done oder error. status_progress läuft von 0 bis 100; in Zwischenschritten bewegt sich der Wert nur bei Modellen, die Audio in Abschnitten verarbeiten.

GET /transcription_model

Transkriptionsmodelle haben zusätzlich response_format (nur Modelle mit diarized_json unterscheiden Sprecher), supported_languages sowie Credit-Preise pro Token und pro Sekunde.

POST /transcription

Diese Route unterstützt keinen Multipart-Upload: Laden Sie die Audio- oder Videodatei zuerst mit POST /file hoch, oder geben Sie eine URL an. Bei Videodateien wird die Tonspur automatisch extrahiert.

Ein fertiger Datensatz (gekürzt):

{
  "ID": 77,
  "slug": "Qm7tR2xa",
  "status": "done",
  "status_progress": 100,
  "text": "Hi team, quick update before Tuesday's launch...",
  "segments": [
    { "start": 0.0, "end": 28.4, "text": "Hi team, quick update before Tuesday's launch...", "speaker": "speaker_0" },
    { "start": 29.0, "end": 37.0, "text": "Thanks Darian. One question from support...", "speaker": "speaker_1" }
  ],
  "speakers": [
    { "label": "speaker_0", "name": "", "color": "#F59E0B" },
    { "label": "speaker_1", "name": "", "color": "#10B981" }
  ],
  "language": "en",
  "duration_seconds": 42.1,
  "credit_cost": "4.22"
}

Aufeinanderfolgende Segmente desselben Sprechers werden zusammengeführt, und eine Pause von zwei Sekunden oder mehr erscheint als eigenes Segment mit einem pause-Wert und leerem text. speaker ist null bei Modellen, die keine Sprecher unterscheiden.

Fehler: 400 "Either file_data_id or source_url is required", 400 "Can't set both file_data_id and source_url", 400 "language is not supported by this transcription model".

GET /transcription, GET /transcription/:id

Listet Ihre Transkriptionen auf (page, size, status) oder ruft eine einzelne anhand von ID oder Slug ab, einschließlich credit_cost. Senden Sie an die Liste keinen Query-Parameter workspace_id.

PATCH /transcription/:id/speakers

Benennt Sprecher um oder ändert ihre Farbe, genau wie Speakers in der App. Nur die gesendeten Felder ändern sich; ein unbekanntes Label wird als neuer Sprecher hinzugefügt.

{
  "speakers": {
    "speaker_0": { "name": "Darian", "color": "#3B82F6" },
    "speaker_1": { "name": "Sam" }
  }
}

Gibt 200 mit der vollständigen Transkription zurück.

POST /transcription/:id/retry

DELETE /transcription/:id

Nutzungsstatistiken

Die Routen /statistics/* und /credits/* benötigen statistics_get, eine Berechtigung, die nur Mitarbeitende von StickyPrompts vergeben können. Schlüssel von Kunden können sie nicht aufrufen. Die Nutzung Ihres Workspace finden Sie in der App unter Nutzung, Credits und Abrechnung, und jeder Medien-Job meldet seine eigenen credit_cost.

Verwandte Seiten