BuddyPro Owner API — OpenAI-kompatibilní V1 Endpoint

version: 1.4 (2026-09-18)

OpenAI-kompatibilní přístup k vaší BuddyPro instanci, navržený pro integraci vlastníků a členů týmu — propojení vašich služeb, automatizací a interních nástrojů s BuddyPro. Tento endpoint přijímá požadavky ve formátu OpenAI Chat Completions API a vrací odpovědi ve stejném formátu, s BuddyPro-specifickými rozšířeními v message (např. image, audio).

BuddyPro End-user API je k dispozici

Pro koncové uživatele je k dispozici samostatné API, které jim umožní vygenerovat vlastní API klíče pracující přímo s jejich osobními profily BuddyPro. Více v dokumentaci End-user API.

Přehled

Vlastnost	Hodnota
Cesta	`POST /v1/chat/completions`
Autentizace	`Authorization: Bearer bapi_...` hlavička
Formát	Kompatibilní s OpenAI Chat Completions
Streaming	Zatím není podporován

Perzistentní paměť a historie konverzací

Na rozdíl od bezstavových LLM API, BuddyPro udržuje dlouhodobou paměť a kompletní historii konverzací pro profil svázaný s každým API klíčem. Každý API požadavek je zpracován stejně jako zpráva odeslaná v Telegramu — je uložen do historie chatu profilu, přispívá k paměti BuddyPro o daném uživateli a ovlivňuje budoucí odpovědi.

To znamená:

Konverzace jsou kumulativní. BuddyPro si pamatuje vše řečené přes API, stejně jako si pamatuje konverzace z Telegramu. Nemusíte (a neměli byste) posílat historii konverzace — stačí poslat aktuální zprávu.
Paměť se buduje postupně. BuddyPro se učí preference, fakta a kontext z API interakcí, stejně jako z Telegram chatů.
Bezstavový režim je k dispozici. Nastavte x_buddy_saveToHistory: false a požadavek nic neuloží — žádná historie chatu, žádné aktualizace paměti, žádné změny profilu. Viz Bezstavový režim.

warning

Neposílejte historii konverzace v poli messages. Posílejte pouze aktuální uživatelskou zprávu. BuddyPro spravuje kontext konverzace na straně serveru.

Soukromí a přístup k datům

danger

Owner API by se NEMĚLO používat k vytváření profilů pro skutečné osoby pomocí testovacích uživatelů. Lidé očekávají soukromé konverzace a často sdílejí osobní nebo citlivé informace. Nejedná se o řešení bezpečné pro koncové uživatele z hlediska soukromí. BuddyPro Owner API nechrání data koncových uživatelů před vlastníkem instance. Vlastník má přístup k historii konverzací a paměti testovacích účtů.

Všechny API klíče v Owner API jsou generovány vlastníkem BuddyPro instance nebo členem týmu. Vlastník má plný přístup ke všem testovacím profilům vytvořeným na jeho instanci — může přepnout na jakýkoli testovací účet pomocí /test v Telegramu, přečíst historii konverzací a vidět vše, co si BuddyPro o daném profilu pamatuje.

Co to znamená v praxi:

Nestavte integraci s profily pro koncové uživatele na BuddyPro Owner API, kde by uživatelé chatovali s BuddyPro přes váš API klíč (např. chatbot na webu) a každý uživatel by měl samostatný testovací profil — vlastník BuddyPro instance by mohl:

Přepnout na jakýkoli z těchto testovacích profilů
Zeptat se BuddyPro: „Řekni mi vše, co o mně víš"
Přečíst kompletní historii konverzací a všechny uložené vzpomínky pro daný profil

Vlastník zná API klíč i identifikátory uživatelů, takže mu nic nebrání v přístupu k jakémukoli profilu vytvořenému jako testovací uživatel.

Doporučené použití Owner API

Interní automatizace a agenti (např. CI/CD boty, monitorovací alerty, interní nástroje)
Integrace služba-služba, kde vlastník profilu je zároveň konzumentem API
Prototypování a vývoj s testovacími uživateli
Použití testovacích uživatelů ve vašich integracích, aby vaše integrace neovlivňovaly vaši osobní historii zpráv a paměť
Scénáře, kde všichni uživatelé API patří do stejné organizace a jsou si vědomi viditelnosti dat
Bezstavové otázky a odpovědi (x_buddy_saveToHistory: false) — bezpečné pro jakékoli použití, protože se nic neukládá

K čemu Owner API NEPOUŽÍVAT

Budování produktů pro koncové uživatele se samostatnými profily vytvořenými jako testovací uživatelé
Vytváření profilů pro skutečné osoby pomocí testovacích účtů
Jakýkoli scénář, kde koncoví uživatelé očekávají, že jejich konverzace zůstanou soukromé před vlastníkem instance

BuddyPro End-user API (Client API)

BuddyPro End-user API (Client API) je nyní k dispozici a umožňuje koncovým uživatelům generovat vlastní API klíče pracující přímo s jejich osobním BuddyPro profilem. V modelu End-user API:

API klíč je generován a znám pouze koncovému uživateli, ne vlastníkovi instance
Vlastník instance nemá přístup k historii konverzací uživatele ani nemůže přes bota přepnout na jeho profil
Koncoví uživatelé mají plné vlastnictví dat svého profilu

Podrobnosti a návod k nastavení najdeš v dokumentaci BuddyPro End-user API.

Nepoužívej Owner API jako náhradu za přístup bezpečný z hlediska soukromí. Pokud potřebuješ soukromí hned, použij x_buddy_saveToHistory: false (bezstavový režim) — nic se neuloží, takže vlastník nemá k čemu přistupovat.

Přeprodej End-user API tvým koncovým uživatelům

Jako vlastník BuddyPro instance můžeš přeprodávat přístup k End-user API svým vlastním koncovým uživatelům. Tvoji uživatelé si vygenerují vlastní klíče k End-user API a nakoupí předplacené kredity na volání API — peníze přistanou na tvém propojeném Stripe účtu a ty si nastavíš vlastní marži nad rámec toho, co ti účtuje BuddyPro.

Jak funguje účtování (dvě nezávislé účetní knihy)

Účetní kniha	Co to je	Kam jdou peníze	Účtováno za požadavek
Kreditová peněženka koncového uživatele	Předplacený zůstatek, který si koncový uživatel dobíjí	Tvůj propojený Stripe účet (přímá platba přes Connect)	Tvoje cena = (co ti účtuje BuddyPro) × (1 + tvoje marže)
Tvoje BuddyPro kredity	BuddyPro účtuje tobě za využití	BuddyPro	Co ti BuddyPro účtuje za požadavek

Tvůj zisk je rozdíl mezi oběma. Peněženka koncového uživatele je na naší straně jen účetní kniha; reálné peníze za ni už leží na tvém Stripe účtu (dorazily tam, když si uživatel dobil kredit).

Předpoklady

Propojený Stripe účet. Propoj svůj Stripe účet přes Stripe OAuth — stejné propojení, které se používá pro prodej předplatných na tvé instanci. Kreditové checkouty koncových uživatelů se vytvářejí jako přímé platby na tomto účtu.
Aktivní předplatné koncového uživatele. Tvoji koncoví uživatelé musí mít aktivní předplatné tvé instance, než si mohou nastavit kredity pro End-user API.
Pouze USD

Příkazy pro vlastníka

Tyto příkazy jsou dostupné pouze vlastníkovi instance nebo členovi týmu.

Příkaz	Popis
`/setApiClientMarkup:{percent}`	Nastav svou marži (%) přidávanou nad rámec toho, co ti účtuje BuddyPro, aplikovanou na využití End-user API tvými koncovými uživateli. Povolený rozsah: 0–500 %. Pokud žádnou nenastavíš, platí výchozí marže 30 %.
`/setApiPaymentUrls:{successUrl} [cancelUrl]`	Nastav přesměrovací URL zobrazené poté, co tvoji koncoví uživatelé dokončí nebo zruší kreditový checkout. Obě musí být platné `https://` odkazy; `cancelUrl` je volitelný. Použij `/setApiPaymentUrls:default` pro reset na výchozí stránky.

Příklad marže: pokud ti BuddyPro účtuje $0,13 za požadavek a nastavíš /setApiClientMarkup:54, peněženka tvého koncového uživatele je zatížena $0,13 × 1,54 ≈ $0,20 a ty si necháváš rozdíl $0,07.

Udržuj své BuddyPro kredity dobité

BuddyPro účtuje tobě z tvých BuddyPro kreditů za každý požadavek End-user API, který tvoji koncoví uživatelé provedou. Pokud ti dojdou BuddyPro kredity, požadavky tvých koncových uživatelů selžou s HTTP 402 owner_billing_unavailable, dokud zůstatek neobnovíš. Nech si na BuddyPro kreditech zapnuté automatické dobíjení, aby provoz koncových uživatelů nikdy nebyl přerušen.

Autentizace

Získání API klíče

info

Ve výchozím stavu používají API konverzace profil, který vygeneroval API klíč — zprávy se ukládají do jeho historie konverzací a přispívají k jeho paměti, i když se v Telegramu nezobrazují. Před generováním klíče použijte v Telegramu /test, aby se klíč svázal s testovacím účtem místo vašeho osobního profilu a API interakce se nemíchaly s vaší osobní historií chatu. Váš skutečný profil vlastníka nebo člena týmu má také správcovské příkazy, které by agenti mohli zneužít; vydání klíče s právy user (viz Práva klíče) k nim přístup odebere, stejně jako odeslání hodnoty user. Viz Izolace uživatelů.

Pošlete tento příkaz svému BuddyPro botovi v Telegramu, ideálně na testovacím účtu:

/generateApiKey:my-app

Obdržíte klíč začínající na bapi_.

Práva klíče

Klíč lze vydat na jedné ze dvou úrovní práv, kterou zadáte jako druhý argument:

Úroveň	Co klíč umí
`full` (výchozí)	Vše, co umí profil, na kterém běží, včetně vašich správcovských příkazů vlastníka/týmu
`user`	Pouze práva běžného uživatele — správcovské příkazy vlastníka/týmu jsou odmítnuty s `permission_denied`

/generateApiKey:my-app:user

Každý klíč, který předáváte třetí straně, vydávejte s právy user.

Co se s právy user nemění: přizpůsobení promptů zůstává dostupné (x_buddy_systemPrompt, x_buddy_systemPromptMode, x_buddy_rolePrompt — dokumentovaná funkce Owner API na obou úrovních), použití se stále účtuje vám a klíč stále běží na vašem profilu, pokud požadavek neobsahuje hodnotu user. Na tomto profilu si zachovává vše, co umí běžný uživatel — čtení jeho historie konverzací a paměti, /getApiStats a příkazy pro API kredity. To, zda požadavek obsahuje user, je na tom, kdo ho odesílá, takže pokud se integrátor nemá k vašemu profilu dostat vůbec, vygenerujte klíč z profilu /test (viz upozornění výše).

Klíče End-user API (/generateClientApiKey) mají vždy práva běžného uživatele — jinak je vydat nelze.

Správa API klíčů

Příkaz	Popis
`/generateApiKey:{název}`	Vytvoření nového API klíče s plnými právy
`/generateApiKey:{název}:user`	Vytvoření nového API klíče omezeného na práva běžného uživatele
`/invalidateApiKey:{název}`	Zneplatnění klíče podle názvu nebo hodnoty
`/getApiStats`	Seznam všech aktivních klíčů, jejich úrovně práv a statistiky použití

Autentizace požadavků

Předejte API klíč přes hlavičku Authorization:

Authorization: Bearer bapi_xxxxxxxxxxxx

Endpoint

POST https://api.buddypro.ai/v1/chat/completions
Authorization: Bearer bapi_xxxxxxxxxxxx
Content-Type: application/json

Požadavek (Request)

Vstupní obsah

Standardní OpenAI pole messages. BuddyPro extrahuje poslední uživatelskou zprávu ke zpracování.

warning

Je povolena pouze jedna user zpráva. BuddyPro spravuje historii konverzací na straně serveru — neposílejte průběh konverzace. Systémové a asistentské zprávy jsou ignorovány.

Pouze text (řetězcový obsah):

{
  "messages": [
    { "role": "user", "content": "Hello, how are you?" }
  ]
}

Multimodální (obsah jako pole):

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image" },
        { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
      ]
    }
  ]
}

Typy částí obsahu

Při použití obsahu jako pole v messages[].content:

Text

{ "type": "text", "text": "What is the weather today?" }

Maximálně 50 000 znaků na textovou část.

Obrázek (image_url)

{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }

Podporované typy URL:

HTTPS URL — musí být veřejně přístupné
Data URI — data:image/png;base64,iVBORw0KGgo...

Maximálně 5 obrázků na požadavek. Maximálně 40 MB na stažení vzdáleného souboru.

Zvukový vstup (input_audio)

{
  "type": "input_audio",
  "input_audio": {
    "data": "<base64>",
    "format": "mp3"
  }
}

Pole:

Pole	Typ	Popis
`data`	string	Base64-kódovaná audio data nebo URL
`format`	string	Formát zvuku: `mp3`, `wav`, `ogg`, `aac`, `flac`
`type`	`"url"` \| `"base64"`	Volitelná nápověda typu dat. Výchozí: `base64`

Zvuk přes URL:

{
  "type": "input_audio",
  "input_audio": {
    "data": "https://example.com/audio.mp3",
    "type": "url",
    "format": "mp3"
  }
}

Dokument / soubor (file)

Dokument (PDF, kancelářský soubor, text atd.) připojte jako obsahovou část file ve stylu OpenAI. BuddyPro dokument na serveru převede na text a použije ho jako kontext — přesně jako když dokument pošlete botovi v Telegramu nebo v mobilu. Model nedostane surová data souboru, takže odpověď asistenta je běžná textová (nebo mediální) odpověď — vstupní dokumenty se zpět nevracejí.

{
  "type": "file",
  "file": {
    "filename": "report.pdf",
    "file_data": "data:application/pdf;base64,<base64>"
  }
}

Pole:

Pole	Typ	Popis
`filename`	string	Navrhovaný název souboru (slouží k odvození typu, když je MIME nejednoznačný)
`file_data`	string	Data URI: `data:<mime>;base64,<base64>`. Vzájemně se vylučuje s `file.url`
`url`	string	Rozšíření BuddyPro — `http(s)` URL hostovaného souboru, který se stáhne místo vloženého `file_data`. Typ dokumentu se určí z obsahu souboru (PDF, soubory Office) nebo z `Content-Type` serveru; obecný `Content-Type` (`application/octet-stream`, `text/plain`) se zpřesní podle přípony v `filename` / URL, pokud jí obsah souboru odpovídá, jinak zůstane beze změny

Dokument přes URL (rozšíření BuddyPro):

{
  "type": "file",
  "file": {
    "filename": "report.pdf",
    "url": "https://example.com/report.pdf"
  }
}

note

file.file_id není podporované — BuddyPro nemá Files API. Dokument předejte vložený přes file_data, nebo hostovaný přes url.

Zvuk se neposílá jako část file — pro zvuk použijte samostatnou část input_audio.

Podporované MIME typy dokumentů: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document (docx), application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx), application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation (pptx), text/plain, text/csv, text/html, text/markdown, application/json, application/xml, text/xml a videotypy video/mp4, video/quicktime, video/webm, video/x-msvideo, video/mpeg (přepsané na text). application/octet-stream se přijímá jako záloha pro neznámý typ. Nepodporované MIME typy vrací kód chyby invalid_media_type.

Max 5 dokumentů na požadavek. Max 40 MB na dokument (načteno z URL nebo dekódováno z base64).

Velké soubory

Dávejte přednost file.url před vloženým file_data. Vložený base64 jede v těle požadavku, které je omezené na ~6 MB (~4 MB skutečného souboru), tedy hluboko pod validačním limitem 40 MB — platí to pro všechna vložená média, nejen dokumenty. Viz Limity médií.

Zvukový výstup (TTS přes Modalities)

Pro vyžádání TTS zvukového výstupu použijte OpenAI-style pole modalities a audio:

{
  "modalities": ["text", "audio"],
  "audio": { "format": "mp3" },
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "input_audio", "input_audio": { "data": "<base64>", "format": "mp3" } }
      ]
    }
  ]
}

Když modalities obsahuje "audio", je TTS aktivní
audio.format je výchozí "mp3", pokud není uvedeno
TTS se aplikuje pouze když je v požadavku přítomen zvukový vstup
audio.voice je přijímán, ale ignorován — hlas nastavuje vlastník bota

Referenční přehled polí požadavku

Pole	Typ	Povinné	Popis
`messages`	array	Ano	Zprávy ve formátu OpenAI. Musí obsahovat přesně 1 uživatelskou zprávu.
`modalities`	`["text"]` \| `["text", "audio"]`	—	Typy výstupu. Zahrňte `"audio"` pro aktivaci TTS
`audio`	object	—	Audio konfigurace: `{ "format": "mp3"\|"wav" }`
`user`	string	—	Vlastní identifikátor uživatele pro izolovaný testovací profil. Když chybí, požadavky používají profil klíče. Viz Izolace uživatelů
`x_buddy_saveToHistory`	boolean	—	Při `false` se nic neuloží do historie chatu, paměti ani profilu. Výchozí: `true`. Viz Bezstavový režim
`x_buddy_systemPrompt`	string	—	Text vlastního systémového promptu (max 50 000 znaků). Viz Vlastní systémový prompt
`x_buddy_systemPromptMode`	string	—	Režim systémového promptu: `"replace"` nebo `"add"`. Výchozí: `"add"`
`x_buddy_rolePrompt`	string	—	Vlastní přepsání role promptu (max 50 000 znaků). Když je nastavené, přeskočí vyhledání či vytvoření role promptu a použije přímo tento text. Viz Vlastní role prompt
`x_buddy_commandResultMode`	string	—	Jak se vracejí výsledky lomítkových příkazů: `"text"` (výchozí, přirozený jazyk) nebo `"deterministic"` (strukturovaný objekt, bez LLM). Jen B2B API klíče. Viz Deterministické výsledky příkazů

Client Request ID

Uveďte přes HTTP hlavičku X-Client-Request-Id:

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: my-app_req-42" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

Maximálně 64 znaků, pouze alfanumerické znaky + pomlčky + podtržítka.

Izolace uživatelů

Ve výchozím stavu používají API požadavky profil, který vygeneroval API klíč. Konverzace se ukládají do historie zpráv tohoto profilu a přispívají k jeho paměti. Pokud byl klíč vygenerován po spuštění /test v Telegramu, je svázaný s tímto testovacím účtem — ne s osobním profilem vlastníka.

Pro vytvoření izolovaných testovacích profilů použijte pole user. Každá jedinečná hodnota user vytvoří zcela samostatný profil s vlastní historií chatu, dlouhodobou pamětí a nastavením.

Režimy:

Režim	Jak aktivovat	Chování
Profil klíče (výchozí)	Vynechte `user`	Použije profil, který vygeneroval API klíč (historie zpráv, nastavení, paměť)
Pojmenovaný uživatel	Nastavte `user` na vlastní identifikátor	Pro každou hodnotu `user` vytvoří samostatný izolovaný profil — hodí se pro specializované profily s konkrétní pamětí nebo historií chatu
Bezstavový	Nastavte `x_buddy_saveToHistory: false`	Nic se neukládá. Lze kombinovat s oběma režimy výše

Příklad pojmenovaného uživatele:

{
  "user": "test-user-joe",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ]
}

Každá jedinečná hodnota user vytvoří zcela izolovaný kontext konverzace s vlastní:

historií chatu
dlouhodobou pamětí
uživatelským profilem a nastavením
oprávněními k příkazům — viz Co hodnota user umí a neumí

Použijte to, když chcete přes jeden API klíč simulovat více uživatelských profilů s různými daty nebo případy použití.

warning

Pojmenované testovací profily nejsou soukromé před vlastníkem API klíče. Vlastník se může do kteréhokoli testovacího profilu přepnout přes /test v Telegramu. Nepoužívejte pole user k vytváření profilů pro skutečné osoby s očekáváním soukromí. Pro přístup koncových uživatelů bezpečný z hlediska soukromí použijte BuddyPro End-user API. Podrobnosti v sekci Soukromí a přístup k datům.

Co hodnota `user` umí a neumí

Izolace je zároveň hranicí oprávnění. Požadavek, který uvádí user, přichází o práva vlastníka instance a týmu, takže příkazy pro správu instance (/createPro, /setupFapi, /disableUser, …) vracejí permission_denied. Zachová si je jen vlastní profil držitele klíče (bez user).

Právě odeslání hodnoty user tedy zabrání agentovi, který drží váš klíč, ve správě vaší instance.

Pravidla validace pro user:

Pouze alfanumerické znaky, pomlčky, podtržítka a tečky (a-z, A-Z, 0-9, -, _, .)
Nesmí to být čistě číselná hodnota (např. 123456789) — kvůli kolizi se skutečnými ID uživatelů
Maximálně 128 znaků
Bez mezer

Bezstavový režim

Nastavte x_buddy_saveToHistory: false a požadavek nic neuloží. V bezstavovém režimu:

se nic neukládá do historie chatu
se neaktualizuje dlouhodobá paměť v Pinecone
se neaktualizuje profil ani se neučí preference
AI přesto odpovídá normálně s využitím existujícího kontextu

Hodí se pro:

Čisté otázky a odpovědi, kterými nechcete zanášet historii profilu
Případy citlivé na soukromí, kde potřebujete jistotu, že se nic neuloží
Testování a prototypování bez vlivu na profil

Bezstavový režim lze kombinovat s jakýmkoli režimem izolace (výchozí, pojmenovaný uživatel nebo profil vlastníka).

Příklad — bezstavová otázka:

{
  "x_buddy_saveToHistory": false,
  "messages": [
    { "role": "user", "content": "What is the best way to build a profitable sales funnel?" }
  ]
}

Příklad — bezstavově s pojmenovaným uživatelem:

{
  "user": "test-user-joe",
  "x_buddy_saveToHistory": false,
  "messages": [
    { "role": "user", "content": "Based on what you know about me, write me 10 ideas to improve my business." }
  ]
}

Vlastní systémový prompt

Systémový prompt BuddyPro můžete pro jednotlivý požadavek nahradit nebo rozšířit pomocí x_buddy_systemPrompt a x_buddy_systemPromptMode.

Režim	Chování
`"replace"`	Úplně nahradí váš systémový prompt
`"add"` (výchozí)	Připojí text k existujícímu systémovému promptu

Režim replace — vlastní persona:

{
  "x_buddy_systemPrompt": "You are now an email writing assistant. Your response must always be an email draft based on the user's request and your know-how. Do not include any explanations or additional text.",
  "x_buddy_systemPromptMode": "replace",
  "messages": [
    { "role": "user", "content": "Write an email about 50% sale on the Business Mastery program." }
  ]
}

Režim add — rozšíření existujícího promptu:

{
  "x_buddy_systemPrompt": "IMPORTANT: Write your next response strictly in Spanish. No comments, just answer.",
  "x_buddy_systemPromptMode": "add",
  "messages": [
    { "role": "user", "content": "How would you write a message to invite people to join my new program?" }
  ]
}

Pravidla validace pro x_buddy_systemPrompt:

Maximálně 50 000 znaků
Značky script (<script>...</script>) se odstraní
Řídicí znaky se odstraní (nové řádky, tabulátory a návraty vozíku zůstávají)

note

Pokud x_buddy_systemPromptMode vynecháte, použije se "add".

Vlastní role prompt

Role prompt AI můžete pro jednotlivý požadavek přepsat pomocí x_buddy_rolePrompt. Když je pole nastavené, BuddyPro přeskočí vyhledání či vytvoření role promptu a použije zadaný text přímo jako definici role.

Jak to funguje: Běžně BuddyPro u každé zprávy vybere vhodnou „roli“ (např. asistent pro programování, kreativní autor, poradce) a načte nebo vygeneruje prompt pro tuto roli. S x_buddy_rolePrompt dodáte role prompt sami a máte tak plnou kontrolu nad personou AI v daném požadavku. Detekce funkcí (vyhledávání na webu, připomínky, generování hudby atd.) dál běží normálně.

Příklad:

{
  "x_buddy_rolePrompt": "You are a minimalist poet who specializes in technical haiku. Keep responses to exactly 3 lines in 5-7-5 syllable format.",
  "messages": [
    { "role": "user", "content": "Write a haiku about code" }
  ]
}

Pravidla validace pro x_buddy_rolePrompt:

Maximálně 50 000 znaků
Značky script (<script>...</script>) se odstraní
Řídicí znaky se odstraní (nové řádky, tabulátory a návraty vozíku zůstávají)
Prázdné řetězce (po sanitizaci) se ignorují — proběhne běžná detekce role

Kombinace s x_buddy_systemPrompt: Obě pole lze použít současně. Systémový prompt určuje základní osobnost a instrukce, role prompt přidává konkrétní roli navrch. Do řetězce promptů se vkládají na různých místech.

Deterministické výsledky příkazů

Dostupnost

Režim "deterministic" je dostupný jen pro B2B API klíče. Požadavky s jiným než B2B API klíčem, které nastaví x_buddy_commandResultMode: "deterministic", se odmítnou s chybou 403 insufficient_permissions. Výchozí režim "text" je dostupný pro všechny typy API.

Ve výchozím stavu vrátí lomítkový příkaz (např. /setVoice:alloy) odpověď v přirozeném jazyce — výsledek příkazu přeformuluje AI, takže se znění mezi voláními liší. Nastav x_buddy_commandResultMode: "deterministic", AI se úplně přeskočí a místo toho dostaneš strukturovaný, strojově čitelný výsledek:

{
  "messages": [
    { "role": "user", "content": "/setVoice:alloy" }
  ],
  "x_buddy_commandResultMode": "deterministic"
}

Odpověď — content je obvykle null (text může nést, když příkaz navíc pošle zprávy, které nejsou jeho výsledkem) a výsledek je v message.x_buddy_commandResult:

{
  "id": "chatcmpl-req_abc123",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "x_buddy_commandResult": {
          "command": "setVoice",
          "status": "success",
          "message": "Voice set to alloy."
        }
      },
      "finish_reason": "stop"
    }
  ]
}

Pole x_buddy_commandResult:

Pole	Typ	Popis
`command`	string	Provedený příkaz bez úvodního lomítka (např. `"setVoice"`)
`status`	string	`"success"` \| `"warning"` \| `"error"` \| `"in_progress"` \| `"awaiting_input"`
`errorCode`	string	Přítomné jen když je `status` `"error"` nebo `"warning"` (a ani tehdy není povinné — některé případy nemají odpovídající kód a důvod nesou v `message`). Jedna z hodnot: `invalid_format`, `invalid_value`, `permission_denied`, `unknown_command`, `not_allowed_via_api`, `precondition_failed`, `client_api_disabled`, `payments_not_configured`, `subscription_required`, `not_found`, `internal_error`, `partial_failure`
`param`	string	Přítomné jen když je chybný právě jeden parametr příkazu — jeho název, shodný s názvy parametrů v syntaxi `:{…}` daného příkazu (např. `"topUpAmount"`). Doplňuje `errorCode`, nikdy ho nenahrazuje: `errorCode` říká, o jaký druh problému jde, `param` říká, který vstup ho způsobil. Chybí, když se výsledek netýká konkrétního vstupu (nesplněná podmínka, interní chyba)
`message`	string	Surový text výsledku příkazu doslovně (nepřeformulovaný AI). Příkazy s více zprávami je spojí oddělené novým řádkem

Odmítnutý vstup, na který ukazuje param (/setupApiCredits:5:2 pod minimálním dobitím):

"x_buddy_commandResult": {
  "command": "setupApiCredits",
  "status": "error",
  "errorCode": "invalid_value",
  "param": "topUpAmount",
  "message": "Error: Minimum topUpAmount is $10."
}

Význam stavů:

success — příkaz doběhl. Informační příkazy (seznamy, statistiky) také vracejí success s obsahem v message.
warning — příkaz doběhl, ale s výhradou, o které bys měl vědět; nic dalšího po tobě není potřeba. Hranice mezi warning a error je právě tahle: pokud výsledek vyžaduje tvůj zásah (spustit příkaz znovu, něco opravit ručně), je to error. warning přijde vždy, když výsledek není čistý úspěch, o který jsi žádal. Nejčastěji požadovaný stav už platil, takže příkaz nic nezměnil (errorCode: "precondition_failed") — /disableLicense na už vypnuté licenci, /enableLicense na zapnuté, /enableMobileApp na instanci, kde je aplikace už zapnutá, /enableMessageAllUsers a /addSystemMessageRecipient pro někoho, kdo to už má, /connectWeb na botovi, který je už propojený s dashboardem, /allowSharedStripe, kde je sdílení už zapnuté, /unassignSubscription na nepřiřazeném předplatném. Nebo příkaz doběhl a nemá co ohlásit, případně volitelný vedlejší krok přeskočil nebo ho nešlo ověřit (bez errorCode — message říká který): /enableMobileApp zavolaný bez e-mailové adresy, /setApplePackage, když kontrola v App Store Connect nemůže proběhnout, /myLicense na botovi, ke kterému není přiřazená žádná licence. Ani jeden seznam není úplný. Příkaz, který tvůj vstup odmítne, sem nepatří a zůstává error — například /createPro s už použitou licencí po tobě potřebuje jinou licenci. Ber warning jako dokončený příkaz, jehož message stojí za to ukázat člověku.
error — příkaz synchronně selhal; errorCode udává strojově čitelný důvod. Běh, který doběhl, ale část jeho položek selhala (např. /update se soubory, které se nepodařilo přepsat, /updateRoles s rolemi, které se nepodařilo aktualizovat), vrací error s errorCode: "partial_failure". Ten kód znamená, že běh doběhl a část práce selhala: message říká kterou a update příkazy navíc vypisují selhané položky v content odpovědi. Vracejí ho i další příkazy — /enableLicense, když se licence zapnula, ale její pro účet ne, a /enableMobileApp, když se aplikace zapnula, ale uvítací e-mail se nepodařilo odeslat. Update, který se před dokončením pozastavil (narazil na limit nákladů nebo příliš často vypršel časový limit), je také error (errorCode: "precondition_failed"): nic už neběží, takže pro pokračování příkaz spusť znovu — nečekej na něj pollováním.
in_progress — práce ještě není hotová a pořád běží: pokračuje v běhu na pozadí (např. synchronizace znalostí přes /update předává další iteraci), nebo už běží jiný update — message říká který případ nastal. Dokončení zjistíš pollováním /updateStatus (deterministicky: in_progress, dokud běh probíhá, success s časem posledního úspěšného updatu, když nic neběží).
Zastavení updatu: /stopUpdate vrací success v obou případech — zaregistruje požadavek na zastavení; message říká, jestli nějaký běh opravdu probíhal. Běžící update se zastaví na hranici své další iterace (to může trvat i několik minut), takže místo předpokladu okamžitého zastavení polluj /updateStatus, dokud nehlásí, že nic neběží. Pokud nic neběželo, zastaralý požadavek na zastavení se automaticky smaže při startu dalšího updatu — nezablokuje ho.
awaiting_input — příkaz čeká na tvou další zprávu. Vrací ho jen /createVoiceClone a nahrání audia, na které čeká, přes API poslat nejde (viz poznámky níže); cokoliv jiného tok zruší.

Poznámky:

Režim ovlivňuje jen požadavky, jejichž zpráva je lomítkový příkaz. Běžné zprávy se chovají přesně jako bez parametru (odpověď AI, žádné pole x_buddy_commandResult).
Onboardingové a účtové toky (/start, /upgrade, /clear) a účtové brány (např. nedostatek kreditů) nejsou běžné příkazy — jejich normální odpovědi se vracejí jako prostý content bez x_buddy_commandResult. Výjimka: když takový tok selže před předáním příkazu s předem nastaveným chybovým výsledkem (např. /clear nevytvoří pozvánku k novému onboardingu), vrátí se ta chyba jako strukturovaný x_buddy_commandResult (status: "error"), ne jako prostý content.
Příkaz proběhne stejně bez ohledu na to, kdo ho posílá; liší se jen to, co po výměně zůstane. Surová message výsledku se uloží do historie chatu jako odpověď asistenta podle stejných pravidel ukládání pro jednotlivé příkazy jako v Telegramu (např. /help a /del se nikdy neukládají). Jestli se vedle ní uloží i vlastní /příkaz volajícího, vyplývá ze dvou pravidel. Zaprvé: požadavek, který uvádí user, se bere jako běžný koncový uživatel bez práv vlastníka instance nebo týmu — zachová si je jen požadavek na vlastním profilu držitele klíče (bez pole user). Zadruhé: /příkaz běžného koncového uživatele se neukládá, ani přes API, ani v Telegramu; uloží se jen Buddyho odpověď. Požadavek s user tedy nechá v historii jen výsledek, požadavek bez něj oba řádky. x_buddy_saveToHistory: false i tak drží požadavek zcela bezstavový. Tajné parametry příkazů (privátní klíče, API klíče, tokeny, licenční klíče — např. /setupFapi, /setApplePrivateKey) se před uložením zprávy zamaskují na ***; výměna, jejíž výsledek obsahuje tajnou hodnotu (např. klíč z /myLicense), se neuloží vůbec. Krok nahrání audia u /createVoiceClone přes API podporovaný není: samotný příkaz vrátí awaiting_input, ale nahrání, které ho dokončí, se musí udělat v Telegramu.
Ve výchozím režimu "text" (nebo když parametr chybí) se nic nemění — výsledky příkazů se vracejí jako text v přirozeném jazyce.
Neznámé příkazy vracejí status: "error" s errorCode: "unknown_command"; příkazy, na které nemáš oprávnění, vracejí errorCode: "permission_denied".
/setupApiCredits rozlišuje své tři podmínky nastavení podle errorCode, takže nemusíš číst zprávu, abys věděl, kdo má jednat: client_api_disabled (vlastník instance nezapnul End-user API), payments_not_configured (vlastník nemá připojený Stripe účet, na který by platba přišla), subscription_required (volající nemá aktivní předplatné instance). Všechny tři jsou status: "error" — každá z nich nechává něco k udělání. Nenesou param: částky, které jsi poslal, jsou v pořádku, stav účtu ne.
Kreditní příkazy (/setupCredits, /changeCreditsTopUp, /setupApiCredits, /changeApiCreditsTopUp) uvádějí param u každého odmítnutí částky, takže samotné invalid_value nikdy není nejednoznačné — dozvíš se, jestli byl odmítnut topUpAmount, nebo rechargeAt. Která hranice to byla, poznáš ze zveřejněných minim/maxim a hodnoty, kterou jsi poslal. Když jsou chybné obě částky, nahlásí se jen první.

Odpověď (Response)

Hlavičky odpovědi

Hlavička	Popis
`x-request-id`	Serverem generované unikátní ID požadavku (vždy přítomno)
`x-client-request-id`	Klientem poskytnuté ID požadavku vrácené zpět (přítomno pouze pokud bylo poskytnuto)
`Content-Type`	`application/json`

Úspěch — pouze text

{
  "id": "chatcmpl-req_abc123def456",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm doing well. How can I help you?"
      },
      "finish_reason": "stop"
    }
  ]
}

Úspěch — výstup obrázku

Když BuddyPro vygeneruje obrázek, objeví se v message.image:

{
  "id": "chatcmpl-req_def456",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's the image you requested:",
        "image": {
          "id": "image_req_def456_generated_image.png",
          "data": "iVBORw0KGgo...",
          "media_type": "image/png",
          "file_name": "generated_image.png",
          "caption": "A sunset over the ocean"
        }
      },
      "finish_reason": "stop"
    }
  ]
}

Úspěch — více obrázků

Když odpověď obsahuje více než jeden obrázek, image nese první z nich (kvůli kompatibilitě s OpenAI SDK) a kompletní seřazená sada je navíc k dispozici v x_buddy_images:

{
  "id": "chatcmpl-req_multi123",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here are the images you requested:",
        "image": {
          "id": "image-1-req_multi123-first.png",
          "data": "iVBORw0KGgo...",
          "media_type": "image/png",
          "file_name": "first.png",
          "caption": "A sunrise over the mountains"
        },
        "x_buddy_images": [
          {
            "id": "image-1-req_multi123-first.png",
            "data": "iVBORw0KGgo...",
            "media_type": "image/png",
            "file_name": "first.png",
            "caption": "A sunrise over the mountains"
          },
          {
            "id": "image-2-req_multi123-second.png",
            "data": "iVBORw0KGgo...",
            "media_type": "image/png",
            "file_name": "second.png",
            "caption": "A sunset over the ocean"
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

Stejný vzor platí pro zvuk: více zvukových položek naplní x_buddy_audios (přičemž x_buddy_audios[0] se rovná audio).

Úspěch — zvukový výstup (hudba / meditace)

Zvuk z hudebních nebo meditačních funkcí je vrácen vždy, bez ohledu na modalities:

{
  "id": "chatcmpl-req_ghi789",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "audio": {
          "id": "audio_req_ghi789_response.ogg",
          "data": "<base64>",
          "format": "ogg",
          "transcript": null,
          "media_type": "audio/ogg",
          "file_name": "response.ogg"
        }
      },
      "finish_reason": "stop"
    }
  ]
}

Úspěch — text + TTS zvuk

Když je TTS aktivní přes modalities a byl odeslán zvukový vstup:

{
  "id": "chatcmpl-req_abc123",
  "object": "chat.completion",
  "created": 1710964800,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Why don't scientists trust atoms? Because they make up everything!",
        "audio": {
          "id": "audio_req_abc123_response.mp3",
          "data": "<base64>",
          "format": "mp3",
          "transcript": "Why don't scientists trust atoms? Because they make up everything!",
          "media_type": "audio/mpeg",
          "file_name": "response.mp3"
        }
      },
      "finish_reason": "stop"
    }
  ]
}

note

Když je přítomen zvukový výstup, transcript obsahuje stejný text jako content (zřetězená textová odpověď).

Referenční přehled polí odpovědi

Nejvyšší úroveň

Pole	Typ	Popis
`id`	string	Unikátní ID dokončení: `chatcmpl-{requestId}`
`object`	string	Vždy `"chat.completion"`
`created`	number	Unix timestamp (sekundy) začátku požadavku
`choices`	array	Pole s jedním výběrem (index 0)

note

Metadata o ID požadavku a době zpracování jsou dostupná přes hlavičky odpovědi (X-Request-Id, X-Client-Request-Id) — nejsou zahrnuty v těle odpovědi.

`choices[0].message`

Pole	Typ	Popis
`role`	string	Vždy `"assistant"`
`content`	string \| null	Zřetězená textová odpověď. `null` pokud pouze média
`audio`	object \| undefined	Zvukový výstup (první zvuková položka). Viz níže
`image`	object \| undefined	Obrázkový výstup (první obrázková položka). Viz níže
`x_buddy_audios`	array \| undefined	Rozšíření BuddyPro. Všechny zvukové položky v pořadí. Přítomné jen když se vrací více než jedna zvuková položka; `x_buddy_audios[0]` se rovná `audio`. Každá položka má stejný tvar jako `message.audio`.
`x_buddy_images`	array \| undefined	Rozšíření BuddyPro. Všechny obrázkové položky v pořadí. Přítomné jen když se vrací více než jedna obrázková položka; `x_buddy_images[0]` se rovná `image`. Každá položka má stejný tvar jako `message.image`.
`x_buddy_commandResult`	object \| undefined	Strukturovaný výsledek lomítkového příkazu — přítomný jen s `x_buddy_commandResultMode: "deterministic"`. Viz Deterministické výsledky příkazů

Vracení všech médií

Jednotlivá pole audio / image zůstávají jednoduchými objekty kvůli kompatibilitě s OpenAI SDK (SDK deserializují message.audio do typovaného objektu). Když odpověď nese více než jednu položku daného typu, je kompletní seřazená sada navíc k dispozici v polích x_buddy_audios / x_buddy_images — klienti OpenAI SDK tato rozšiřující pole prostě ignorují. U jedné (nebo žádné) položky daného typu se pole vynechá a odpověď se nemění. Když je přítomný zvukový výstup, transcript se nastavuje jen na první zvukové položce.

`message.audio` (OpenAiAudioOutput)

Pole	Typ	Popis
`id`	string	Identifikátor zvuku: `audio_{requestId}_{fileName}`
`data`	string	Base64-kódovaná audio data
`format`	string	Formát zvuku (např. `mp3`, `ogg`, `wav`)
`transcript`	string \| undefined	Textový přepis (stejný jako `content` při TTS)
`media_type`	string	MIME typ (např. `audio/mpeg`, `audio/ogg`)
`file_name`	string	Doporučený název souboru

`message.image` (OpenAiImageOutput — rozšíření BuddyPro)

Pole	Typ	Popis
`id`	string	Identifikátor obrázku: `image_{requestId}_{fileName}`
`data`	string	Base64-kódovaná obrazová data
`media_type`	string	MIME typ (např. `image/png`)
`file_name`	string	Doporučený název souboru
`caption`	string	Popis obrázku

Chybová odpověď

Všechny chyby používají strukturovaný formát s objektem error:

{
  "error": {
    "message": "Invalid or inactive API key",
    "type": "authentication_error",
    "statusCode": 401,
    "code": "invalid_api_key",
    "param": null
  }
}

Důležité

Vždy kontrolujte tělo odpovědi na přítomnost pole error — nespoléhejte se pouze na HTTP stavový kód. Za určitých podmínek může být HTTP stavový kód 200, i když tělo odpovědi obsahuje chybu.

Pole chyby

Pole	Typ	Popis
`error.message`	string	Čitelný popis chyby
`error.type`	string	Kategorie chyby
`error.statusCode`	number	HTTP stavový kód
`error.code`	string \| null	Strojově čitelný kód chyby
`error.param`	string \| null	Parametr požadavku, který způsobil chybu

Typy chyb

HTTP Status	`type`	Popis
400	`invalid_request_error`	Chybně formátovaný požadavek, chybějící pole, neplatný obsah
401	`authentication_error`	Chybějící nebo neplatný API klíč
403	`permission_error`	Nedostatečná oprávnění
405	`method_not_allowed`	Špatná HTTP metoda
410	`gone`	Zastaralý endpoint již není k dispozici
429	`rate_limit_error`	Překročen limit požadavků
500	`server_error`	Interní chyba serveru

Běžné chybové kódy

Kód	Význam
`invalid_json`	Tělo požadavku není platný JSON
`missing_required_parameter`	Chybí povinné pole
`missing_api_key`	V hlavičce `Authorization` není API klíč
`invalid_api_key`	API klíč nebyl nalezen nebo je neaktivní
`invalid_value`	Pole má špatný typ nebo neplatnou hodnotu
`invalid_text_content`	Text je prázdný nebo překračuje limit 50 000 znaků
`invalid_content_type`	Neznámý typ části obsahu
`invalid_content`	Obsah nemá žádné použitelné položky
`invalid_media_data`	Data média jsou neplatná, stažení selhalo nebo překročena velikost
`invalid_media_type`	Nepodporovaný MIME typ (zahrnuje nepodporované MIME typy obrázků, zvuku i dokumentů)
`invalid_audio_format`	Nepodporovaný formát zvuku
`invalid_image_count`	Příliš mnoho obrázků (max 5)
`invalid_document_count`	Příliš mnoho dokumentů (max 5 částí `file`)
`invalid_parameter`	Neplatná hodnota parametru (např. chybné `user`, `x_buddy_systemPrompt`, `x_buddy_systemPromptMode`, `x_buddy_rolePrompt`, `x_buddy_saveToHistory` nebo `x_buddy_commandResultMode`)
`insufficient_permissions`	API klíč nemá potřebná oprávnění
`endpoint_deprecated`	Verze API byla ukončena a již není k dispozici
`rate_limit_exceeded`	Více než 30 požadavků za minutu

Limity požadavků

30 požadavků za minutu na jeden API klíč

Omezení

Omezení	Detail
Bez streamingu	Streaming zatím není podporován
Jedna uživatelská zpráva	Pouze 1 uživatelská zpráva v poli `messages` (BuddyPro spravuje historii)
Bez výběru modelu	Pole `model` je přijímáno, ale ignorováno — BuddyPro má vlastní implementaci modelů
Bez statistik využití	Objekt `usage` není zahrnut v odpovědích
Priorita prvního média	V odpovědi je zobrazena pouze první zvuková a první obrázková položka
Hlas nelze ovládat	`audio.voice` je přijímán, ale ignorován — hlas nastavuje vlastník bota

Limity médií

Max 5 obrázků na požadavek
Max 5 dokumentů na požadavek (obsahové části file) — při překročení se vrací kód chyby invalid_document_count
Max 40 MB na stažení média (načteno z URL nebo dekódováno z base64 — obrázky, zvuk i dokumenty)
Vložený base64 je omezený přenosem (~6 MB tělo požadavku). Celé tělo požadavku se musí vejít do limitu ~6 MB, takže vložená base64 média — data URI v image_url, input_audio.data nebo file_data — jsou fakticky omezená zhruba na ~4 MB skutečného souboru (base64 přidává ~33 %), tedy hluboko pod limitem 40 MB výše. Pro větší soubory pošlete místo toho URL (image_url s HTTPS URL, input_audio s type: "url" nebo file.url): stáhne se na serveru a dostane celý 40MB rozpočet.
Max 50 000 znaků na textovou část obsahu
Podporované typy dokumentů: PDF, Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx), prostý text, CSV, HTML, Markdown, JSON, XML a videotypy mp4/quicktime/webm/avi/mpeg (přepsané na text). Nepodporované MIME typy vrací invalid_media_type. Viz Dokument / soubor (file)

Rychlý start

curl — Text

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What is the weather like today?" }
    ]
  }'

curl — Multimodální (obrázek + text)

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ]
  }'

curl — Dokument (soubor + text)

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Summarize this report." },
          { "type": "file", "file": { "filename": "report.pdf", "file_data": "data:application/pdf;base64,<base64>" } }
        ]
      }
    ]
  }'

curl — Zvukový vstup s TTS výstupem

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "modalities": ["text", "audio"],
    "audio": { "format": "mp3" },
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "input_audio", "input_audio": { "data": "<base64>", "format": "mp3" } }
        ]
      }
    ]
  }'

curl — Pojmenovaný uživatel (izolace)

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "test-user-joe",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

curl — Bezstavový režim

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "x_buddy_saveToHistory": false,
    "messages": [
      { "role": "user", "content": "What is 2 + 2?" }
    ]
  }'

curl — Vlastní role prompt

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "x_buddy_rolePrompt": "You are a minimalist poet who specializes in technical haiku.",
    "messages": [
      { "role": "user", "content": "Write a haiku about code" }
    ]
  }'

curl — Vlastní systémový prompt

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "x_buddy_systemPrompt": "You are a helpful coding assistant. Only answer programming questions.",
    "x_buddy_systemPromptMode": "replace",
    "messages": [
      { "role": "user", "content": "How do I reverse a string in JavaScript?" }
    ]
  }'

Důležité poznámky

Neposílejte historii konverzace — posílejte pouze aktuální uživatelskou zprávu. BuddyPro spravuje kontext konverzace interně.
Ve výchozím stavu používají API požadavky profil, který vygeneroval API klíč — konverzace se ukládají do jeho historie a přispívají k jeho paměti. Před generováním klíče použijte /test, aby se klíč svázal s testovacím účtem. Pro další izolované profily použijte pole user.
Pro bezstavové otázky a odpovědi použijte x_buddy_saveToHistory: false — nic se neuloží do historie chatu, paměti ani profilu.
Pojmenované testovací profily (pole user) nejsou soukromé před vlastníkem API klíče. Nepoužívejte je pro soukromá data skutečných osob.
API zpracovává požadavky synchronně — odpověď je vrácena, jakmile BuddyPro dokončí generování.
SSRF ochrana: URL směřující na privátní/interní síťové adresy jsou blokované.

Historie verzí

Verze	Vydáno	Změny
`1.4`	2026-09-18	Obsahová část dokument (`file`) s vloženým `file_data` nebo `file.url`; pole `x_buddy_images` / `x_buddy_audios`, když odpověď nese více než jeden obrázek nebo zvukovou položku; `invalid_document_count`; přepracované Limity médií (dokumenty, přenosový limit vloženého base64)
`1.3`	2026-09-10	Deterministické výsledky příkazů (`x_buddy_commandResultMode`, stavy výsledku, `errorCode` / `param`, pravidla ukládání příkazové výměny do historie); Práva klíče — Owner klíče s právy `user`, omezení End-user klíčů na práva běžného uživatele
`1.2`	2026-07-17	Model přeprodeje End-user API — brána opt-inu vlastníka, marže přeprodeje (`/setApiClientMarkup`), HTTP 402 mapované na `payment_required`
`1.1`	2026-04-25	První verzované vydání — izolace uživatelů, `x_buddy_saveToHistory`, odstraňování rolí

Přehled​

Perzistentní paměť a historie konverzací​

Soukromí a přístup k datům​

Doporučené použití Owner API​

K čemu Owner API NEPOUŽÍVAT​

BuddyPro End-user API (Client API)​

Přeprodej End-user API tvým koncovým uživatelům​

Jak funguje účtování (dvě nezávislé účetní knihy)​

Předpoklady​

Příkazy pro vlastníka​

Udržuj své BuddyPro kredity dobité​

Autentizace​

Získání API klíče​

Práva klíče​

Správa API klíčů​

Autentizace požadavků​

Endpoint​

Požadavek (Request)​

Vstupní obsah​

Typy částí obsahu​

Text​

Obrázek (image_url)​

Zvukový vstup (input_audio)​

Dokument / soubor (file)​

Zvukový výstup (TTS přes Modalities)​

Referenční přehled polí požadavku​

Client Request ID​

Izolace uživatelů​

Co hodnota user umí a neumí​

Bezstavový režim​

Vlastní systémový prompt​

Vlastní role prompt​

Deterministické výsledky příkazů​

Odpověď (Response)​

Hlavičky odpovědi​

Úspěch — pouze text​

Úspěch — výstup obrázku​

Úspěch — více obrázků​

Úspěch — zvukový výstup (hudba / meditace)​

Úspěch — text + TTS zvuk​

Referenční přehled polí odpovědi​

Nejvyšší úroveň​

choices[0].message​

message.audio (OpenAiAudioOutput)​

message.image (OpenAiImageOutput — rozšíření BuddyPro)​

Chybová odpověď​

Pole chyby​

Typy chyb​

Běžné chybové kódy​

Limity požadavků​

Omezení​

Limity médií​

Rychlý start​

curl — Text​

curl — Multimodální (obrázek + text)​

curl — Dokument (soubor + text)​

curl — Zvukový vstup s TTS výstupem​

curl — Pojmenovaný uživatel (izolace)​

curl — Bezstavový režim​

curl — Vlastní role prompt​

curl — Vlastní systémový prompt​

Důležité poznámky​

Historie verzí​

Přehled

Perzistentní paměť a historie konverzací

Soukromí a přístup k datům

Doporučené použití Owner API

K čemu Owner API NEPOUŽÍVAT

BuddyPro End-user API (Client API)

Přeprodej End-user API tvým koncovým uživatelům

Jak funguje účtování (dvě nezávislé účetní knihy)

Předpoklady

Příkazy pro vlastníka

Udržuj své BuddyPro kredity dobité

Autentizace

Získání API klíče

Práva klíče

Správa API klíčů

Autentizace požadavků

Endpoint

Požadavek (Request)

Vstupní obsah

Typy částí obsahu

Text

Obrázek (image_url)

Zvukový vstup (input_audio)

Dokument / soubor (file)

Zvukový výstup (TTS přes Modalities)

Referenční přehled polí požadavku

Client Request ID

Izolace uživatelů

Co hodnota `user` umí a neumí

Bezstavový režim

Vlastní systémový prompt

Vlastní role prompt

Deterministické výsledky příkazů

Odpověď (Response)

Hlavičky odpovědi

Úspěch — pouze text

Úspěch — výstup obrázku

Úspěch — více obrázků

Úspěch — zvukový výstup (hudba / meditace)

Úspěch — text + TTS zvuk

Referenční přehled polí odpovědi

Nejvyšší úroveň

`choices[0].message`

`message.audio` (OpenAiAudioOutput)

`message.image` (OpenAiImageOutput — rozšíření BuddyPro)

Chybová odpověď

Pole chyby

Typy chyb

Běžné chybové kódy

Limity požadavků

Omezení

Limity médií

Rychlý start

curl — Text

curl — Multimodální (obrázek + text)

curl — Dokument (soubor + text)

curl — Zvukový vstup s TTS výstupem

curl — Pojmenovaný uživatel (izolace)

curl — Bezstavový režim

curl — Vlastní role prompt

curl — Vlastní systémový prompt

Důležité poznámky

Historie verzí