BuddyPro Owner API — OpenAI-kompatibilní V1 Endpoint

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 — již brzy

Samostatné API pro koncové uživatele je plánováno v budoucí verzi, které jim umožní generovat vlastní API klíče pracující přímo s jejich osobními profily. Více v sekci Soukromí a přístup k datům.

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ů.
Zatím neexistuje bezstavový režim. Každý požadavek je uložen a ovlivňuje profil. Budoucí rozšíření API bude podporovat bezstavové dotazy, které se neukládají do paměti ani historie, ale zatím není k dispozici.

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

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ů

Připravované BuddyPro End User API

Budoucí BuddyPro End User API tento problém vyřeší tím, že umožní 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í ani paměti uživatele
Koncoví uživatelé mají plné vlastnictví dat svého profilu

Dokud nebude End User API k dispozici, nepoužívejte Owner API jako náhradu za přístup bezpečný z hlediska soukromí.

Autentizace

Získání API klíče

warning

Když si vygenerujete API klíč, je svázaný s profilem, který ho vytvořil. Všechny API konverzace se ukládají do historie zpráv tohoto profilu a přispívají k jeho paměti — i když tyto konverzace v Telegramu nevidíte. Generujte API klíče na testovacím účtu (nejdříve použijte /test v Telegramu), aby se API interakce 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.

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_.

Správa API klíčů

Příkaz	Popis
`/generateApiKey:{název}`	Vytvoření nového API klíče
`/invalidateApiKey:{název}`	Zneplatnění klíče podle názvu nebo hodnoty
`/getApiStats`	Seznam všech aktivních klíčů 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ě 20 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"
  }
}

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

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.

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 — 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

`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 20 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
`invalid_audio_format`	Nepodporovaný formát zvuku
`invalid_image_count`	Příliš mnoho obrázků (max 5)
`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
Bez bezstavového režimu	Všechny požadavky se ukládají do paměti a historie chatu. Bezstavové dotazy přijdou v budoucí aktualizaci

Limity médií

Max 5 obrázků na požadavek
Max 40 MB na stažení média (média načtená z URL)
Max 20 000 znaků na textovou část obsahu

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 — 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" } }
        ]
      }
    ]
  }'

Důležité poznámky

Neposílejte historii konverzace — posílejte pouze aktuální uživatelskou zprávu. BuddyPro spravuje kontext konverzace interně.
API konverzace se ukládají do profilu a historie zpráv vlastníka klíče, i když se v Telegramu nezobrazují.
Před generováním API klíčů použijte /test, aby API interakce zůstaly oddělené od vašeho osobního profilu.
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é.

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​

Připravované BuddyPro End User API​

Autentizace​

Získání API 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)​

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

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

Client Request ID​

Odpověď (Response)​

Hlavičky odpovědi​

Úspěch — pouze text​

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

Ú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 — Zvukový vstup s TTS výstupem​

Důležité poznámky​

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

Připravované BuddyPro End User API

Autentizace

Získání API 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)

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

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

Client Request ID

Odpověď (Response)

Hlavičky odpovědi

Úspěch — pouze text

Úspěch — výstup obrázku

Ú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 — Zvukový vstup s TTS výstupem

Důležité poznámky