Modellek és média

Ez az oldal a modellkatalógust és az összes médiavégpontot ismerteti. A chatmodelleket adod meg ai_model_id értékként a beszélgetésekben és a futtatásokban. A videónak, a beszédnek, a zenének és az átírásnak saját modellkatalógusa van, és mindegyik ugyanazt a feladatmintát követi.

Minden útvonal a https://api.stickyprompts.com/api/v1 címhez képest értendő, és minden kérés tartalmazza az Authorization: Bearer $STICKY_API_KEY headert.

Konvenciók

• Azonosítók és slugok. Minden generálásnak és átírásnak van numerikus ID azonosítója és 8 karakteres slug értéke. A GET /<resource>/:id és a POST /<resource>/:id/retry bármelyiket elfogadja, a DELETE /<resource>/:id viszont csak a numerikus azonosítót.
• A decimális számok stringek. A kreditárak és -költségek (credit_cost, credit_cost_per_*, multiplier) JSON-stringként érkeznek, például "0.000015".
• Mezőnevek írásmódja. A rekordokban a snake_case mezők mellett PascalCase ID, CreatedAt, UpdatedAt és DeletedAt szerepel. Lásd: Hibák, lapozás és kvóták.
• Listák. A page (alapértéke 1) és a size (alapértéke 10) paraméterrel lapozhatók, a legújabb elemmel kezdődnek, és X-Total-Count, X-Page és X-Page-Size headert kapnak. A törzs egy egyszerű tömb.
• Kvóta. A díjköteles munkát indító útvonalak 429 {"error":"Quota exceeded","reason":"..."} választ adnak, ha a csomag kerete elfogyott.
• Korlátozott modellek. Ha egy munkaterületi szabály tiltja a választott modellt, a létrehozó hívások 403 {"error":"the selected model has been restricted by your organization"} választ adnak.

Chatmodellek

A chatmodelleket a numerikus ID azonosítja. A name megjelenített név, nem azonosító. API-kulcs használatakor a munkaterületed modellhozzáférési szabályai és adatrezidencia-szabályzata is érvényesül: azok a modellek, amelyeket nem használhatsz, selectable: false értékkel és egy restriction_reason mezővel érkeznek.

GET /ai_model

A chatmodell-katalógust listázza megjelenítési sorrendben. Az elavult modellek is szerepelnek benne, hacsak nem adod meg a legacy=false paramétert.

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]));

200-as válasz (egy elem látható, az értékek szemléltető jellegűek):

[
  {
    "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
  }
]

Hasznos mezők: a tools a képességeket sorolja fel (file_upload, file_generation, image_generation, web_search, web_fetch, code_execution, remote_mcp és továbbiak), a reasoning_efforts az engedélyezett gondolkodási szinteket, a successor az elavult modell utódját nevezi meg, a supported_file_extensions pedig a mellékleteket korlátozza (üres érték esetén nincs korlátozás). A katalógusban nincs kontextusablak-méret, USD-ár vagy benchmarkmező.

GET /ai_model/:id

Egy modellt ad vissza a numerikus ID alapján. A successor itt nincs betöltve.

GET /ai_model/filters

Visszaadja azokat az értékeket (ismétlődés nélkül), amelyek alapján a katalógus szűrhető:

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

Ha egy listához egyik modellnek sincs értéke, a lista [] helyett null.

GET /ai_model/restricted

Elavult. Csak azokat a modelleket jelzi, amelyeket a munkaterületed egy modellszintű szabálya tilt. Helyette a GET /ai_model válaszának selectable jelzőjét használd.

Képgenerálás

A képgenerálás szinkron: a hívás akkor tér vissza, amikor a kép elkészült. A szerver a StickyPrompts által beállított képmodellt használja; egyedül a prompttal irányíthatod (méretre, darabszámra vagy képarányra nincs paraméter).

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);

200-as válasz, egy fájlrekorddal:

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

A kép a path címen érhető el, amely közvetlen tárhely-URL. Tartsd meg az ID értéket: file_id értékként használhatod szerkesztéshez, videó kezdőképkockájaként és a fájlvégpontokon. Figyelj a camelCase fileType mezőre.

Hibák: 400, ha hiányzik a prompt; 500 {"error":"image generation produced no output file"}, ha a modell nem ad vissza semmit; 500 a hibaüzenettel, ha a modell hibázik, vagy az adatrezidencia-szabályok tiltják a szolgáltatót. A kliensben állíts be bőven elegendő időkorlátot.

POST /image_generation/edit

Szerkeszt egy saját képet, és új fájlt ad vissza. A forrásfájl nem változik.

200-as válasz: egy új fájlrekord. Ha a fájl nem a tiéd, a válasz 404 {"error":"file not found or access denied"}.

Háttérfeladatok: videó, beszéd, zene, átírás

Ez a négy erőforrás ugyanazt a mintát követi:

1. Válassz modellt

   A GET /<kind>_model az adott típus katalógusát adja vissza. A modellt a numerikus ID alapján válaszd ki. A default: true jelző az alkalmazásban előre kiválasztott modellt jelöli, de az API nem áll vissza rá automatikusan: mindig küldd el a modell azonosítóját.

2. Hozd létre a feladatot

   A POST /<kind> ellenőrzi a kérést, a kvótát és a hozzáférést, majd 201 kóddal válaszol, queued állapotú feladattal.

3. Kérdezd le, amíg el nem készül

   Hívd a GET /<kind>/:id végpontot, amíg a status értéke done vagy error nem lesz. Ezekhez a feladatokhoz nincsenek webhookok vagy eseménystreamek; néhány másodpercenként kérdezd le az állapotot.

4. Vedd át az eredményt

   Videónál, beszédnél és zenénél a fájl az output_file_data.path címen van. Átírásnál a text és a segments magában a rekordban található.

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);

Mind a négyre érvényes szabályok:

• A modellazonosító kötelező. Ha kihagyod, vagy ismeretlen azonosítót küldesz, általános 500 "Failed to create ..." hibát kapsz, nem 400-ast.
• Költség. A GET /<kind>/:id válaszában szerepel a credit_cost, vagyis a feladatért felszámított kredit. A listaválaszokban itt mindig "0" áll.
• Adatrezidencia. Ha a munkaterületed rezidenciaszabályzata tiltja a modell szolgáltatóját, a rendszer elfogadja a feladatot, de az utána elbukik, és az error mezőbe a szabályzat üzenete kerül. Az ilyen modellek a katalógusban selectable: false értékkel szerepelnek, ezért ezt előbb ellenőrizd.
• Újrapróbálás. A POST /<kind>/:id/retry újra sorba állítja az error állapotú feladatot (más állapotban 400 "Only failed ... can be retried" a válasz), és ismét ellenőrzi a hozzáférést és a kvótát.
• Törlés. A DELETE /<kind>/:id (numerikus azonosítóval) 204-es választ ad, akkor is, ha nem talált semmit. Logikai törlésről (soft delete) van szó, a kimeneti fájlt nem távolítja el.
• Listák szűrése a ?status=<value> paraméterrel.

Minden médiamodellnek van ID, name, powered_by, version, description, multiplier, default, sort és selectable mezője, szükség esetén pedig restriction_reason mezője is. A katalógusok nincsenek lapozva.

Videógenerálás

Állapotok: queued, majd processing, végül done vagy error.

GET /video_generation_model

A videómodellek további mezői: supported_aspect_ratios (üres érték esetén bármelyik képarány), supported_resolutions (az első az alapértelmezett), resolution_duration_limits (felbontásonként, "*" tartalékértékkel, {min_duration_seconds, max_duration_seconds} alakban, ahol a 0 korlátlant jelent), resolution_pricing (felbontásonkénti credit_cost_per_second), interpolation_support (none, start_only vagy full), max_reference_images és 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
  }'

201-es válasz (rövidítve):

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

done állapotban az output_file_data.path a .mp4 fájlra mutat, és az actual_duration_seconds és a credit_cost is kitöltődik. A content_policy_violation: true azt jelenti, hogy a szolgáltató biztonsági szűrője elutasította a kérést.

Az ellenőrzési hibák 400-as kódot kapnak pontos üzenettel, például "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" vagy "attached file must be an image". Ha valaki más fájlját használod, a válasz 403 "you do not have permission to use this file".

GET /video_generation, GET /video_generation/:id

Listázd a videófeladataidat (page, size, status), vagy kérj le egyet azonosító vagy slug alapján, a credit_cost értékkel együtt. Ha nem található: 404 {"error":"Video generation not found"}.

POST /video_generation/:id/retry

DELETE /video_generation/:id

Szövegfelolvasás

Állapotok: queued, majd processing, végül done vagy error.

GET /tts_generation_model

A beszédmodellek további mezői: supported_languages (üres érték esetén bármelyik nyelv), valamint egy tts_voice_set, amelynek voices elemeiben voice_id (ezt küldd voice értékként), name, gender, language, accent, description, preview_audio_url és default szerepel.

POST /tts_generation

201-es válasszal adja vissza a feladatot. done állapotban a hanganyag (.wav vagy .mp3, attól függően, mit adott vissza a szolgáltató) az output_file_data.path címen érhető el. Hibák: 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

Zenegenerálás

Állapotok: queued, majd processing, végül done vagy error.

GET /music_generation_model

A zenemodellek további mezői: min_duration_seconds és max_duration_seconds (a 0 korlátlant jelent), supported_output_formats (az első az alapértelmezett), credit_cost_per_generation és credit_cost_per_second.

POST /music_generation

done állapotban a zeneszám az output_file_data.path címen van, az esetleges dalszöveg pedig a lyrics mezőben. A fájlkiterjesztés ahhoz igazodik, amit a szolgáltató ténylegesen visszaadott, ezért eltérhet az output_format értékétől. Hibák: 400 a korlátokon kívüli hossznál vagy nem támogatott formátumnál.

GET /music_generation, GET /music_generation/:id

POST /music_generation/:id/retry

DELETE /music_generation/:id

Hangátírás

Állapotok: queued, fetching, preparing, processing, végül done vagy error. A status_progress 0-tól 100-ig halad; fokozatosan csak azoknál a modelleknél változik, amelyek darabokban dolgozzák fel a hangot.

GET /transcription_model

Az átírómodellek további mezői: response_format (a beszélőket csak a diarized_json modellek címkézik), supported_languages, valamint tokenenkénti és másodpercenkénti kreditárak.

POST /transcription

Ezen az útvonalon nincs multipart feltöltés: előbb töltsd fel a hang- vagy videófájlt a POST /file végponttal, vagy adj meg egy URL-t. Videófájloknál a rendszer automatikusan kinyeri a hangsávot.

Egy kész rekord (rövidítve):

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

Az ugyanattól a beszélőtől származó szomszédos szegmensek összevonódnak, a legalább kétmásodperces szünet pedig külön szegmensként jelenik meg, pause értékkel és üres text mezővel. A beszélőket nem szétválasztó modelleknél a speaker értéke null.

Hibák: 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

Listázd az átírásaidat (page, size, status), vagy kérj le egyet azonosító vagy slug alapján, a credit_cost értékkel együtt. A listázásnál ne küldj workspace_id query-paramétert.

PATCH /transcription/:id/speakers

Átnevezheted vagy átszínezheted a beszélőket, ugyanúgy, mint az alkalmazásban a Speakers résznél. Csak az elküldött mezők változnak; az ismeretlen címke új beszélőként kerül be.

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

200-as választ ad, a teljes átírással.

POST /transcription/:id/retry

DELETE /transcription/:id

Felhasználási statisztikák

A /statistics/* és a /credits/* útvonalakhoz statistics_get jogosultság kell, amelyet csak a StickyPrompts munkatársai adhatnak meg. Ügyfélkulccsal ezek nem hívhatók. A munkaterületed felhasználását az alkalmazásban látod (lásd: Felhasználás, kreditek és számlázás), és minden médiafeladat saját credit_cost értéket ad vissza.

Kapcsolódó oldalak