BuddyPro End-user API (Client API)

version: 1.3 (2026-09-18)

OpenAI-kompatibilní API přístup pro koncové uživatele BuddyPro — kdokoli, kdo BuddyPro používá, si může vygenerovat vlastní klíč a programově přistupovat ke svému osobnímu profilu BuddyPro. Jde o API placené za použití (pay-per-use), účtované z předplacených kreditů zakoupených přes tu BuddyPro instanci, kterou používáš; cenu za jeden požadavek stanovuje daná instance. API přijímá požadavky ve stejném formátu jako OpenAI Chat Completions API a vrací odpovědi ve stejném formátu, s BuddyPro rozšířeními v poli message (např. image, audio).

Toto není Owner API. Pokud jsi vlastník BuddyPro instance nebo člen týmu a stavíš interní nástroje, automatizace nebo servisní integrace, použij místo toho Owner API (samostatná B2B dokumentace).

Přehled

Vlastnost	Hodnota
Cesta	`POST /v1/chat/completions`
Autentizace	hlavička `Authorization: Bearer bapi_B2C_...`
Formát	kompatibilní s OpenAI Chat Completions
Účtování	předplacené kredity (Stripe) — kupované přes tvou BuddyPro instanci, účtované za požadavek
Streaming	zatím nepodporován

Kdo může Client API používat

Client API klíč si může vygenerovat kterýkoli přihlášený uživatel BuddyPro — nejen vlastníci instance nebo členové týmu — za předpokladu, že vlastník instance Client API povolil. Client API je ve výchozím stavu vypnuté; pokud ho vlastník nezapnul, /generateClientApiKey vrátí chybu a existující klíče přestanou fungovat. Jakmile je povolené, klíč je svázaný s tvým osobním profilem BuddyPro: každý požadavek se zpracuje, jako bys poslal zprávu v Telegramu, s plným přístupem k tvé historii konverzací, dlouhodobé paměti a osobnímu nastavení.

Aby klíč skutečně fungoval, musíš nastavit účtování kreditů — a to má dva požadavky:

Aktivní předplatné té BuddyPro instance, kterou používáš.
Instance musí přijímat platby za API kredity. Účtování zajišťuje instance (její vlastník), který stanovuje cenu za požadavek; instanci, jejíž vlastník platby za API nepovolil, ti kredity prodat nemůže.

Pokud některý z požadavků není splněn, /setupApiCredits vrátí vysvětlující chybu (viz Nastavení účtování kreditů).

POZNÁMKA: Client API klíč má vždy práva běžného uživatele, i když ho vygeneroval vlastník instance nebo člen jejího týmu. Příkazy pro správu instance (/enableClientApi, /setApiClientMarkup a podobné) jsou odmítnuty s permission_denied. Práva se týkají pouze oprávnění: klíč stále vystupuje jako profil, na kterém jeho požadavky běží — s historií konverzací, pamětí a příkazy běžného uživatele tohoto profilu — a použití se stále účtuje majiteli klíče.

Předplatné musí zůstat aktivní. Přístup je vázaný na živé předplatné, ne na tvůj limit zpráv: vyčerpaný měsíční limit zpráv API nezavře, ale zrušené, propadlé nebo nezaplacené předplatné ano — chybou 403 (viz Předplatné už není aktivní).

Trvalá paměť a historie konverzací

Stejně jako rozhraní v Telegramu BuddyPro udržuje dlouhodobou paměť a plnou historii konverzací tvého profilu. Každý API požadavek se zpracuje přesně jako zpráva poslaná v Telegramu — uloží se do tvé historie, přispívá do paměti BuddyPro o tobě a ovlivňuje budoucí odpovědi.

To znamená:

Konverzace se kumulují. BuddyPro si pamatuje vše, co bylo řečeno přes API, stejně jako si pamatuje konverzace z Telegramu. Historii konverzace nemusíš (a neměl bys) posílat — pošli jen aktuální zprávu.
Paměť se buduje v čase. BuddyPro se z API interakcí učí preference, fakta a kontext stejně jako z chatů v Telegramu.
K dispozici je bezstavový režim. Nastav x_buddy_saveToHistory: false pro požadavek, který nic neukládá — žádná historie chatu, žádné aktualizace paměti, žádné změny profilu. Viz Bezstavový režim.

Neposílej historii konverzace v poli messages. Pošli jen aktuální zprávu uživatele. BuddyPro ukládá a spravuje kontext konverzace na straně serveru.

Soukromí a přístup k datům

Client API poskytuje koncovým uživatelům plné vlastnictví dat. Na rozdíl od Owner API (kde vlastník instance může přepnout na kterýkoli testovací profil, který vytvořil) je Client API navržené kolem soukromí uživatele:

Tvůj API klíč je jen tvůj. Vlastník BuddyPro instance tvůj klíč nevidí.
Tvůj profil je soukromý. Vlastník instance nemůže přes bota přepnout na tvůj osobní Telegram profil — Telegram user ID jsou číselná a příkaz /test číselná ID zcela blokuje.
Tvé izolované profily jsou chráněné. Profily, které vytvoříš pomocí pole user, jsou přiřazené k tvému vlastnímu API klíči. Vlastník instance na ně nemůže přepnout — bot vynucuje, že můžeš přepínat jen na profily vytvořené tvými vlastními klíči.

Co to znamená v praxi:

Client API je bezpečné používat pro osobní integrace, automatizace a nástroje, kde chceš programový přístup ke svému vlastnímu profilu BuddyPro. Svá data ovládáš přes tentýž klíč, který sis vygeneroval.

Autentizace

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

Pošli tento příkaz svému BuddyPro botovi v Telegramu:

/generateClientApiKey:my-app

Název (:my-app) je volitelný — pokud ho vynecháš, vygeneruje se automaticky. Dostaneš klíč začínající na bapi_B2C_.

Ulož si tento klíč bezpečně — už se znovu nezobrazí. Zneplatnění: /invalidateApiKey:my-app (můžeš použít název klíče nebo samotný řetězec klíče)

Po vygenerování klíče musíš před prvním API požadavkem nastavit účtování kreditů.

POZNÁMKA: Ve výchozím stavu požadavky používají tvůj osobní profil BuddyPro — zprávy se ukládají do tvé historie a přispívají do tvé paměti. Pole user použij k vytvoření dalších izolovaných profilů se samostatnou historií konverzací a pamětí (např. pro různé projekty nebo kontexty). Viz Izolace uživatelů.

Nastavení účtování kreditů

Client API vyžaduje předplacené kredity přes Stripe. Po vygenerování klíče spusť:

/setupApiCredits:100:20

Otevře se Stripe checkout, kde nakoupíš svou počáteční dobíječku kreditů. Dva parametry jsou:

Parametr	Popis	Minimum	Maximum
`topUpAmount`	Částka v USD k vložení, když kredity dojdou	$10	$10 000
`rechargeAt`	Prahová hodnota zůstatku kreditů, která spustí automatické dobití	$2	$10 000

Příklad: /setupApiCredits:100:20 — nakup zpočátku $100, automaticky dobíjej po $100 vždy, když zůstatek klesne pod $20.

Kredity se automaticky dobíjejí přes tvou uloženou platební metodu, když zůstatek klesne pod práh rechargeAt. Po počátečním nastavení už nemusíš ručně dobíjet.

Platba jde instanci, ne BuddyPro. Tvůj checkout kreditů a uložená platební metoda zpracovává ta BuddyPro instance, kterou používáš (její vlastník), který stanovuje cenu za požadavek. Částka odečtená ze zůstatku za jeden požadavek je cena dané instance.

Požadavky pro nastavení. /setupApiCredits vrátí chybu, pokud:

Nemáš aktivní předplatné instance: "An active subscription is required to set up Client API credits."
Instance není nastavená pro přijímání API plateb: "This instance is not set up to accept API credit payments yet. Please contact the instance owner."

Jakmile je účtování aktivní, použij /changeApiCreditsTopUp (níže) k úpravě částek — opětovné volání /setupApiCredits vrátí chybu, že účtování už je nastavené.

Změna nastavení kreditů

Ke změně částky dobití nebo prahu dobíjení bez spuštění nového Stripe checkoutu:

/changeApiCreditsTopUp:20:5

Nastaví automatické dobíjení na $20 a práh na $5. Tvůj existující vztah k účtování zůstává zachován — není potřeba nový checkout.

Správa API klíčů

Příkaz	Popis
`/generateClientApiKey:{name}`	Vytvoří nový Client API klíč (`name` je volitelný)
`/invalidateApiKey:{name or bapi_B2C_...}`	Zneplatní klíč podle názvu nebo řetězce klíče
`/getApiStats`	Vypíše všechny tvé aktivní API klíče a využití
`/setupApiCredits:{topUp}:{rechargeAt}`	Nastaví účtování (poprvé — otevře Stripe checkout)
`/changeApiCreditsTopUp:{topUp}:{rechargeAt}`	Upraví částku automatického dobíjení a práh

Autentizace požadavků

API klíč předej v hlavičce Authorization:

Authorization: Bearer bapi_B2C_xxxxxxxxxxxx

Endpoint

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

Požadavek

Vstupní obsah

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

Povolená je pouze jedna user zpráva. BuddyPro spravuje historii konverzací na straně serveru — neposílej jednotlivé tahy konverzace. system a assistant 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 uvnitř messages[].content:

Text

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

Max. 50 000 znaků na jednu 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ě dostupná
Data URI — data:image/png;base64,iVBORw0KGgo...

Max. 5 obrázků na požadavek. Max. 40 MB na vzdálené stažení.

Zvukový vstup (input_audio)

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

Pole:

Pole	Typ	Popis
`data`	string	Zvuková data v base64 nebo URL
`format`	string	Formát zvuku: `mp3`, `wav`, `ogg`, `aac`, `flac`
`type`	`"url"` \| `"base64"`	Volitelný typ 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řipoj 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šleš 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"
  }
}

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

Zvuk se neposílá jako část file — pro zvuk použij 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ávej 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žij OpenAI 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", TTS je zapnuté
audio.format je výchozí "mp3", pokud je vynecháno
TTS se uplatní jen tehdy, když je v požadavku přítomen zvukový vstup
audio.voice je přijímáno, ale ignorováno — hlas nastavuje vlastník bota

Reference 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. Přidej `"audio"` pro zapnutí TTS
`audio`	object	—	Konfigurace zvuku: `{ "format": "mp3"\|"wav" }`
`user`	string	—	Vlastní identifikátor uživatele pro izolovaný profil. Viz Izolace uživatelů
`x_buddy_saveToHistory`	boolean	—	Když `false`, nic se neuloží do historie, paměti ani profilu. Výchozí: `true`. Viz Bezstavový režim

Pole pro přepis promptu nejsou v Client API k dispozici. x_buddy_systemPrompt, x_buddy_systemPromptMode a x_buddy_rolePrompt nejsou podporovány pro Client API klíče — system a role prompty vlastníka instance nelze přepsat na úrovni požadavku. Poslání kteréhokoli z těchto polí vrátí chybu 400 unsupported_parameter.

Client Request ID

Předej přes HTTP hlavičku X-Client-Request-Id (max. 64 znaků, alfanumerické + pomlčky + podtržítka):

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

Izolace uživatelů

Ve výchozím stavu API požadavky používají tvůj osobní profil BuddyPro — všechny konverzace se ukládají do tvé historie a přispívají do tvé paměti.

K vytvoření izolovaných profilů se samostatnou historií konverzací a pamětí použij pole user. Každá unikátní hodnota user vytvoří plně samostatný profil — vhodné pro různé projekty, persony nebo kontexty.

Režim	Jak aktivovat	Chování
Osobní profil (výchozí)	Vynech `user`	Použije tvůj vlastní profil (historie, nastavení, paměť)
Izolovaný profil	Nastav `user` na vlastní identifikátor	Vytvoří samostatný profil na hodnotu — vlastní historie, paměť, nastavení
Bezstavový	Nastav `x_buddy_saveToHistory: false`	Nic se neukládá. Lze kombinovat s oběma režimy

Příklad izolovaného profilu:

{
  "user": "work-assistant",
  "messages": [
    { "role": "user", "content": "Help me prepare for my 3pm meeting." }
  ]
}

Validační pravidla pro user:

Pouze alfanumerické znaky, pomlčky, podtržítka a tečky (a-z, A-Z, 0-9, -, _, .)
Nesmí být čistě číselná hodnota
Max. 128 znaků, bez mezer

Bezstavový režim

Nastav x_buddy_saveToHistory: false pro požadavek, který nic neukládá. V bezstavovém režimu:

Nic se neuloží do historie chatu
Žádné aktualizace dlouhodobé paměti
Žádné aktualizace profilu ani učení preferencí
AI přesto normálně odpovídá s využitím existujícího kontextu

Příklad — bezstavové Q&A:

{
  "x_buddy_saveToHistory": false,
  "messages": [
    { "role": "user", "content": "What is the best way to start a business?" }
  ]
}

Odpověď

Hlavičky odpovědi

Hlavička	Popis
`x-request-id`	Serverem generované unikátní ID požadavku (vždy přítomné)
`x-client-request-id`	Klientem dodané ID požadavku vrácené zpět (pokud bylo zadáno)
`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! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ]
}

Úspěch — obrázkový výstup

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 funkcí hudby nebo meditace se vrací 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 zapnuté přes modalities a byl poslá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"
    }
  ]
}

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

Reference polí odpovědi

Nejvyšší úroveň

Pole	Typ	Popis
`id`	string	Unikátní ID completion: `chatcmpl-{requestId}`
`object`	string	Vždy `"chat.completion"`
`created`	number	Unixový timestamp (v sekundách) začátku požadavku
`choices`	array	Pole s jedinou volbou (index 0)

Poznámka: ID požadavku a metadata o době zpracování jsou dostupná přes hlavičky odpovědi (X-Request-Id, X-Client-Request-Id) — nejsou součástí těla odpovědi.

`choices[0].message`

Pole	Typ	Popis
`role`	string	Vždy `"assistant"`
`content`	string \| null	Zřetězená textová odpověď. `null`, pokud jen 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`.

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	Zvuková data v base64
`format`	string	Formát zvuku (např. `mp3`, `ogg`, `wav`)
`transcript`	string \| undefined	Textový přepis (stejný jako `content` u TTS)
`media_type`	string	MIME typ (např. `audio/mpeg`, `audio/ogg`)
`file_name`	string	Navržený název souboru

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

Pole	Typ	Popis
`id`	string	Identifikátor obrázku: `image_{requestId}_{fileName}`
`data`	string	Obrázková data v base64
`media_type`	string	MIME typ (např. `image/png`)
`file_name`	string	Navržený název souboru
`caption`	string	Popisek/popis obrázku

Chybové odpovědi

Formát chybové odpovědi

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 zkontroluj v těle odpovědi pole error — nespoléhej se pouze na HTTP status kód. Za určitých okolností může být HTTP status 200, i když tělo odpovědi obsahuje chybu.

Pole chyby

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

Typy chyb

HTTP status	`type`	Popis
400	`invalid_request_error`	Chybně tvořený požadavek, chybějící pole, neplatný obsah
401	`authentication_error`	Chybějící nebo neplatný API klíč
402	`payment_required`	Účtování není nastavené, nedostatek kreditů, nebo účtování instance nedostupné (specifické pro Client API — viz níže)
403	`permission_error`	Nedostatečná oprávnění
405	`method_not_allowed`	Špatná HTTP metoda
410	`gone`	Zastaralý endpoint už není dostupný
429	`rate_limit_error`	Překročen limit počtu požadavků
500	`server_error`	Interní chyba serveru

Běžné kódy chyb

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íč nenalezen nebo neaktivní
`invalid_value`	Pole má špatný typ nebo neplatnou hodnotu
`invalid_text_content`	Text je prázdný nebo přesahuje limit 50 000 znaků
`invalid_content_type`	Neznámý typ části obsahu
`invalid_content`	Obsah nemá žádné použitelné položky
`invalid_media_data`	Neplatná data média, selhalo stažení, nebo přesah limitu velikosti
`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ř. špatný `user` nebo `x_buddy_saveToHistory`)
`unsupported_parameter`	Byl poslán parametr, který Client API klíče nepodporují (např. `x_buddy_systemPrompt`, `x_buddy_systemPromptMode`, `x_buddy_rolePrompt`)
`insufficient_permissions`	API klíči chybí potřebná oprávnění, nebo vlastník instance Client API zakázal (viz Client API zakázáno)
`subscription_stopped`	Předplatné, ke kterému API klíč patří, bylo zrušené a jeho zaplacené období skončilo (viz Předplatné už není aktivní)
`subscription_unpaid`	U předplatného, ke kterému API klíč patří, selhala platba nebo je nezaplacená faktura
`subscription_required`	Zkušební období, ke kterému API klíč patří, skončilo bez předplatného
`endpoint_deprecated`	Verze API byla zastarána a už není dostupná
`rate_limit_exceeded`	Více než 30 požadavků za minutu

Chyby specifické pro Client API (HTTP 402)

Client API přidává čtyři kódy chyb spojených s účtováním. Všechny používají type: "payment_required":

HTTP status	`code`	Popis
402	`billing_not_set_up`	Účtování zatím nenastaveno. Nejprve spusť v Telegramu `/setupApiCredits:{topUp}:{rechargeAt}`.
402	`insufficient_credits`	Zůstatek kreditů je nulový nebo záporný a automatické dobití selhalo nebo je v cooldownu — zkontroluj svou platební metodu. Dobití se automaticky zopakuje při dalším požadavku.
402	`insufficient_credits_recharging`	Zůstatek kreditů byl nulový nebo záporný, ale tento požadavek právě spustil úspěšnou platbu automatického dobití — kredity dorazí během pár sekund. Odpověď nese hlavičku `Retry-After: 5`; stačí za chvíli zopakovat.
402	`owner_billing_unavailable`	Instance, kterou používáš, momentálně nemůže účtovat za využití (její vlastní účetní zůstatek je vyčerpán). To je na straně vlastníka instance, ne na tvé — zkus to později.

Příklad — účtování není nastaveno:

{
  "error": {
    "message": "Billing not set up. Please set up billing to use the Buddy API. Call /setupApiCredits:{topUpAmount}:{rechargeAt} first.",
    "type": "payment_required",
    "statusCode": 402,
    "code": "billing_not_set_up",
    "param": null
  }
}

Příklad — nedostatek kreditů:

{
  "error": {
    "message": "Insufficient credits. Auto-recharge failed or is in cooldown — please check your payment method and try again later.",
    "type": "payment_required",
    "statusCode": 402,
    "code": "insufficient_credits",
    "param": null
  }
}

Příklad — nedostatek kreditů, dobití probíhá (odpověď obsahuje Retry-After: 5):

{
  "error": {
    "message": "Insufficient credits. An automatic recharge was just initiated and payment succeeded — credits will be available shortly. Please retry.",
    "type": "payment_required",
    "statusCode": 402,
    "code": "insufficient_credits_recharging",
    "param": null
  }
}

Příklad — účtování instance nedostupné:

{
  "error": {
    "message": "Service is temporarily unavailable for billing reasons. Please try again later.",
    "type": "payment_required",
    "statusCode": 402,
    "code": "owner_billing_unavailable",
    "param": null
  }
}

Předplatné už není aktivní (HTTP 403)

Přístup ke Client API se řídí tvým předplatným BuddyPro instance, ne limitem zpráv. Dokud je předplatné živé, API funguje dál — včetně situace, kdy máš vyčerpaný měsíční limit zpráv pro chat v Telegramu, protože API požadavky se platí z kreditů a tento limit nečerpají. Pokud skončí samotné předplatné, API se uzavře chybou 403 a type: "permission_error":

HTTP status	`code`	Popis
403	`subscription_stopped`	Tvoje předplatné bylo zrušené a jeho zaplacené období skončilo. Obnov ho příkazem `/start` v chatu. Zrušené předplatné funguje až do konce období, které už máš zaplacené.
403	`subscription_unpaid`	Platba tvého předplatného opakovaně selhala nebo je nezaplacená faktura. Aktualizuj platební metodu.
403	`subscription_required`	Tvoje zkušební období skončilo bez předplatného. Je vyžadované aktivní předplatné.

Tato kontrola běží před kontrolami kreditů, takže propadlému předplatnému se cestou k odmítnutí nikdy nestrhne automatické dobití — a vždy se vyhodnocuje na účtu, kterému API klíč patří, bez ohledu na to, zda požadavek obsahuje pole user.

Příklad — předplatné už není aktivní:

{
  "error": {
    "message": "Your Buddy subscription is no longer active. Please restart it with /start in the chat to restore API access.",
    "type": "permission_error",
    "statusCode": 403,
    "code": "subscription_stopped",
    "param": null
  }
}

Client API zakázáno (HTTP 403)

Client API je opt-in na straně vlastníka a vlastník instance ho může kdykoli zakázat. Dokud je zakázané, každý požadavek — včetně dříve vydaných, platných klíčů — je odmítnut chybou 403 insufficient_permissions. Klíče se neruší; obnoví funkčnost, jakmile vlastník Client API znovu povolí.

{
  "error": {
    "message": "The Client API is not enabled for this instance. The instance owner must enable it first.",
    "type": "permission_error",
    "statusCode": 403,
    "code": "insufficient_permissions",
    "param": null
  }
}

Limity počtu požadavků

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

Rychlý start

Krok 1 — Vygeneruj klíč

/generateClientApiKey:my-app

Krok 2 — Nastav účtování

/setupApiCredits:100:20

Dokonči Stripe checkout. Tvůj účet má nyní $100 v kreditech a bude se automaticky dobíjet, když zůstatek klesne pod $20.

Krok 3 — Odešli svůj první požadavek

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_B2C_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello! What do you know about me?" }
    ]
  }'

curl — bezstavový režim

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_B2C_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "x_buddy_saveToHistory": false,
    "messages": [
      { "role": "user", "content": "What is the best way to start a profitable business?" }
    ]
  }'

curl — izolovaný profil

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_B2C_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "work-assistant",
    "messages": [
      { "role": "user", "content": "Help me write a professional email." }
    ]
  }'

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

curl -X POST https://api.buddypro.ai/v1/chat/completions \
  -H "Authorization: Bearer bapi_B2C_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_B2C_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_B2C_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" } }
        ]
      }
    ]
  }'

Omezení

Omezení	Detail
Žádný streaming	Streaming zatím není podporován
Jediná uživatelská zpráva	Pouze 1 `user` 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 modelu
Bez statistik využití	Objekt `usage` není součástí odpovědí
Rozhoduje první médium	Na jednu volbu se propíše jen první zvuk a první obrázek z odpovědi
Hlas nelze řídit	`audio.voice` je přijímáno, ale ignorováno — 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 jedno 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šli 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 jednu 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)

Důležité poznámky

Neposílej historii konverzace — pošli jen aktuální zprávu uživatele. BuddyPro ukládá a spravuje kontext konverzace interně.
Účtování kreditů je vyžadováno před prvním požadavkem. Nastav ho jednou pomocí /setupApiCredits:{topUp}:{rechargeAt}. Vyžaduje aktivní předplatné instance a instance musí přijímat API platby.
Účtování zajišťuje tvá instance. Checkouty kreditů a cenu za požadavek stanovuje ta BuddyPro instance, kterou používáš (její vlastník), ne přímo BuddyPro.
Kredity se automaticky dobíjejí, když zůstatek klesne pod nastavený práh, pomocí tvé uložené Stripe platební metody.
Tvá data jsou tvá. Vlastník instance nemůže přes rozhraní bota číst tvou historii konverzací ani přepnout na tvůj profil či tvé izolované profily.
Ochrana proti SSRF: URL směřující na privátní/interní síťové adresy jsou blokovány.

Historie verzí

Verze	Vydáno	Změny
`1.3`	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.2`	2026-09-10	Předplatné už není aktivní (HTTP 403, kódy `subscription_*`); End-user klíče mají vždy práva běžného uživatele
`1.1`	2026-07-17	Model přeprodeje — brána opt-inu vlastníka (klíče a `/setupApiCredits` fungují, až když instance End-user API povolí), cenu za požadavek stanovuje instance včetně své marže, HTTP 402 mapované na `payment_required`, 402 rozlišující úspěšné automatické dobití
`1.0`	2026-07-17	První vydání (vyšlo společně s `1.1`)

Přehled​

Kdo může Client API používat​

Trvalá paměť a historie konverzací​

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

Autentizace​

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

Nastavení účtování kreditů​

Změna nastavení kreditů​

Správa API klíčů​

Autentizace požadavků​

Endpoint​

Požadavek​

Vstupní obsah​

Typy částí obsahu​

Text​

Obrázek (image_url)​

Zvukový vstup (input_audio)​

Dokument / soubor (file)​

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

Reference polí požadavku​

Client Request ID​

Izolace uživatelů​

Bezstavový režim​

Odpověď​

Hlavičky odpovědi​

Úspěch — pouze text​

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

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

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

Úspěch — text + TTS zvuk​

Reference polí odpovědi​

Nejvyšší úroveň​

choices[0].message​

message.audio (OpenAiAudioOutput)​

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

Chybové odpovědi​

Formát chybové odpovědi​

Pole chyby​

Typy chyb​

Běžné kódy chyb​

Chyby specifické pro Client API (HTTP 402)​

Předplatné už není aktivní (HTTP 403)​

Client API zakázáno (HTTP 403)​

Limity počtu požadavků​

Rychlý start​

Krok 1 — Vygeneruj klíč​

Krok 2 — Nastav účtování​

Krok 3 — Odešli svůj první požadavek​

curl — bezstavový režim​

curl — izolovaný profil​

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

curl — dokument (soubor + text)​

curl — zvukový vstup s TTS výstupem​

Omezení​

Limity médií​

Důležité poznámky​

Historie verzí​