Przewodnik po API naszej aplikacji
1. Wprowadzenie
Nasze API umożliwia programistyczne korzystanie z funkcji naszej aplikacji AI, w tym tworzenie wątków konwersacji i wysyłanie zapytań do różnych modeli.
2. Autentykacja
Do komunikacji z API wymagane jest uwierzytelnienie za pomocą tokenu z konta usługowego (Service Account), którego wygenerowanie jest możliwe dla każdego workspace przez osobę posiadającą do niego odpowiednie uprawnienia (np. właściciel workspace).
Tokeny Service Account
Tokeny Service Account zapewniają bezpieczny i kontrolowany dostęp do API.
Format nagłówka autoryzacji:
Authorization: Token <token>
Gdzie <token> to unikalny token dostępu generowany w panelu konta usługowego.
Zarządzanie tokenami
Możesz zarządzać swoimi tokenami API w panelu administratora:
- Tworzenie tokenów - token po utworzeniu w panelu Service Account zostanie zapisany do schowka i jego ponowne odtworzenie nie jest możliwe,
- Unieważnianie tokenów - aby uniemożliwić korzystanie z danego tokenu, usuń go w panelu zarządzania Service Accounts,
- Rotacja tokenów - wygeneruj nowy token i dokonaj podmiany w swoim systemi, przed usunięciem poprzedniego.
Uprawnienia tokenów
Generowane tokeny umożliwiają korzystanie z aplikacji w obrębie danego workspace, dla którego zostały wygenerowane. Konta usługowe (które posługują się generowanymi tokenami) mają uprawnienia do odczytu, co znaczy, że nie mają możliwości np. edycji instrukcji systemowych workspace ani nadawania uprawnień do workspace innym użytkownikom aplikacji.
3. Dostępne endpointy
- w większości endpointów, konieczne będzie podanie specjalnego
uuidworkspace. Można go skopiować z poziomu panelu Service Account w aplikacji.
Zarządzanie wątkami
Pobranie wątków
GET /api/chatbot/<uuid:chatbot_uuid>/threads/
Parametry zapytania: - Brak wymaganych parametrów
Przykład odpowiedzi:
{
"count": "integer",
"next": "string",
"previous": "string",
"results": [
{
"uuid": "string",
"title": "string",
"date_created": "datetime",
"date_updated": "datetime",
"chatbot": "uuid"
}
]
}
Utworzenie wątku
POST /api/chatbot/threads/
Przykład zapytania:
{
"title": "Nowy wątek",
"description": "Opis wątku (opcjonalne)",
"chatbot": "44da2c7d-9449-4df7-bd8a-2eaedca53535"
}
Przykład odpowiedzi:
{
"uuid": "thread uuid [string]",
"user": "userid [int]",
"title": "string",
"description": "string",
"date_created": "datetime",
"date_updated": "datetime",
"chatbot": "uuid"
}
Pobierz/zaktualizuj/usuń wątek
GET/PATCH/DELETE /api/chatbot/<uuid:chatbot_uuid>/threads/<uuid:uuid>/
Przykład zapytania (PATCH):
{
"title": "string"
}
{
"title": "string",
"description": "",
"date_created": "2025-06-17T10:01:16.877187Z",
"date_updated": "2025-06-17T10:12:21.832964Z"
}
Przykład zapytania (GET): - brak
Przykład odpowiedzi:
{
"uuid": "d72c0bae-46fb-485e-9995-0c6ed5c951ca",
"user": 311,
"title": "string",
"description": "",
"date_created": "2025-06-17T10:01:16.877187Z",
"date_updated": "2025-06-17T10:01:16.877202Z",
"chatbot": "257cbd6a-6458-483d-a96b-d365be6efe32"
}
Wiadomości
Pobierz wiadomości
GET /api/chatbot/<uuid:chatbot_uuid>/threads/<uuid:thread_uuid>/messages/
Przykład zapytania: - brak
Przykład odpowiedzi:
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "integer",
"role": "string",
"message": "string",
"date": "date",
"thread": {
"uuid": "thread_uuid"
},
"rating": "integer",
"temp_files_names": [],
"search_suggestions": null,
"grounding_sources": null,
"executable_code": null,
"code_execution_result": null
},
{
"id": "integer",
"role": "string",
"message": "string",
"date": "date",
"thread": {
"uuid": "thread_uuid"
},
"rating": "integer",
"temp_files_names": [],
"search_suggestions": null,
"grounding_sources": null,
"executable_code": null,
"code_execution_result": null
}
]
}
Modele
| Endpoint | Metoda | Opis |
|---|---|---|
/api/models/ |
GET |
Pobierz dostępne modele |
/api/models/{id}/ |
GET |
Pobierz szczegóły modelu |
{
"models": [
{
"id": 10,
"display_name": "Gemini 2.5 Pro",
"alias_model_name": "gemini-pro-2.5",
"full_model_name": "gemini-2.5-pro-preview-05-06",
"input_tokens_limit": 1048576,
"output_tokens_limit": 65536,
"date_created": "2025-05-22T11:32:10.086288Z",
"date_updated": "2025-05-22T11:32:10.086298Z",
"input_modalities": [
"text",
"image",
"audio",
"video"
],
"input_modalities_display": [
"Text",
"Image",
"Audio",
"Video"
],
"output_modalities": [
"text"
],
"output_modalities_display": [
"Text"
],
"features": [
"function_calling",
"code_execution",
"search",
"structured_output",
"thinking",
"caching"
],
"features_display": [
"Function calling",
"Code execution",
"Search",
"Structured output",
"Thinking",
"Caching"
],
"thinking_configuration": false
},
]
}
Zapytania do AI
- jako
modelnależy podaćalias_model_namejednego z dostępnych modeli. - jako
featuresmożna podać jedną wartość zfeaturesmodelu z wyjątkiemthinking(na tą chwilę obsługiwane są jedyniesearchorazcode_execution)
Streamowanie odpowiedzi
POST /api/chatbot/<uuid:chatbot_uuid>/threads/<uuid:thread_uuid>/stream/
Przykład zapytania:
{
"features": [],
"model": "gemini-flash-2.0",
"text": "witaj",
"thinking": false
}
Przykład odpowiedzi (Server-Sent Events (SSE) stream):
- id to identyfikator wiadomości
{"data": {"text": "Cześć", "id": 12, "timestamp": "2025-06-13T15:15:33.394532+00:00"}}
Jednorazowa całkowita dopowiedź
POST /api/chatbot/<uuid:chatbot_uuid>/threads/<uuid:thread_uuid>/response/
Przykład zapytania:
- jako model należy podać alias_model_name jednego z dostępnych modeli.
{
"model": "string",
"text": "string",
}
Przykład odpowiedzi:
- id to identyfikator wiadomości
{
"data": {
"finish_reason": "NATURAL_STOP",
"text": "Hej 😄\n",
"timestamp": "2025-06-16T14:22:13.816808+00:00",
"id": 7557
}
}
Jednorazowa odpowiedź bez wątku
POST /api/single_response/
Przykład zapytania:
- jako model należy podać alias_model_name jednego z dostępnych modeli.
{
"model": "string",
"text": "string",
}
Przykład odpowiedzi
{
"text": "Cześć\n"
}
Jednorazowe zapytanie z plikami
POST /api/chatbot/<uuid:chatbot_uuid>/threads/<uuid:thread_uuid>/integration_response/
Przykład zapytania z podaniem pliku jako publiczny URL:
- jako model należy podać alias_model_name jednego z dostępnych modeli.
{
"model": "model",
"text": "string",
"files": ["string_url"],
"streaming": false/true,
"thinking": false/true
}
Przykład zapytania z podaniem pliku w formularzu:
- jako model należy podać alias_model_name jednego z dostępnych modeli.
{
"model": "model",
"text": "string",
"streaming": false/true,
"thinking": false/true
}
+ pass files with a form file field
Przykład odpowiedz:
- id to identyfikator wiadomości
{"data": {"text": "string", "id": "integer", "timestamp": "datetime"}}
{
"data": {
"finish_reason": "NATURAL_STOP",
"text": "Cześć! ",
"timestamp": "2025-06-17T12:50:47.718787+00:00",
"id": "message id [int]"
}
}
4. FAQ
Jak uzyskać token API?
Token API można wygenerować w panelu "Konta usługowe" / "Service Account". Tokeny są powiązane z konkretnym kontem usługowym (Service Account).
Czy mogę używać API w aplikacji frontendowej?
Nie zalecamy używania tokenów API bezpośrednio w aplikacjach frontendowych ze względów bezpieczeństwa. Zamiast tego, zaimplementuj własny backend jako warstwę pośrednią, która będzie komunikować się z naszym API.
Co zrobić, gdy otrzymuję błąd 429?
Błąd 429 oznacza przekroczenie limitu zapytań. Należy zaimplementować mechanizm wycofania i ponownych prób.
Co się stanie, gdy mój token wygaśnie?
Tokeny powiązane z kontami usługowymi nie mają terminiu ważności.