Jak to działa
MarkdownCo dzieje się z żądaniem między Twoim programem a modelem.
Pełny przewodnik
Wysyłasz żądanie do Ailoot API tak samo jak bezpośrednio do OpenAI, Anthropic lub Google. Ailoot sprawdza klucz i saldo, przekazuje żądanie modelowi, zwraca odpowiedź w tym samym formacie i pobiera opłatę według rzeczywistego zużycia.
Jeden klucz — trzy formaty
Format określa ścieżka żądania, a nie model. Ten sam model Claude można wywołać przez OpenAI Chat, OpenAI Responses lub Anthropic Messages — odpowiedź będzie miała format wywołanej ścieżki.
| Format | Ścieżka | Kto z niego korzysta |
|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions | OpenAI SDK, większość czatów i edytorów, n8n, LangChain |
| OpenAI Responses | /v1/responses | Codex CLI, OpenAI Agents SDK, nowsze wersje SDK |
| Anthropic Messages | /v1/messages | Claude Code, Anthropic SDK, Zed, Cline |
| Gemini | /v1beta/models/{model}:generateContent | Gemini CLI, Google GenAI SDK |
Rozliczenia: rezerwa i jednorazowe obciążenie
- Przed wysłaniem nowego żądania tekstowego Ailoot rezerwuje środki na szacowane wejście i typową odpowiedź, z uwzględnieniem limitu (
max_tokens) oraz warunków konkretnego modelu. Jeśli rezerwacja nie mieści się w wolnym saldzie lub limicie klucza, przekazywany limit można zmniejszyć tylko dla modelu i metody, które rzeczywiście go przestrzegają, i nie poniżej 256 tokenów ani ustalonego minimalnego rozmiaru odpowiedzi. Dla obrazów, wideo i dźwięku na wyjściu nadal rezerwowany jest pełny koszt wyniku. - Po odpowiedzi opłata jest pobierana raz, według rzeczywistego zużycia. Niewykorzystana rezerwa natychmiast wraca na saldo.
- Jeśli odpowiedź kosztuje więcej niż rezerwa, różnica jest pobierana z wolnego salda. Saldo nigdy nie spada poniżej zera.
- Jeśli środków nie wystarcza nawet na minimalną rezerwę, żądanie nie jest wysyłane: otrzymasz czytelny błąd 402, a opłata nie zostanie pobrana.
- Za błąd, po którym nie ma wyniku, nie pobiera się opłaty.
Szczegóły i przykład obliczeń znajdują się na stronie Rezerwacja i obciążenie.
Błędy z Request ID
Każda odpowiedź otrzymuje identyfikator żądania: w nagłówku X-Request-ID i w treści błędu. Błędy są zwracane w JSON zgodnym z wywołanym formatem, dlatego SDK rozpoznają je prawidłowo. Jeśli coś pójdzie nie tak, wyślij Request ID do pomocą techniczną — dzięki temu znajdziemy żądanie w ciągu minuty.
{
"code": "API_KEY_REQUIRED",
"error": {
"code": "invalid_api_key",
"message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
"param": null,
"reason": "invalid_api_key",
"request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
"type": "invalid_request_error"
},
"message": "No API key was sent with the request. Nothing was charged. …"
}Strumieniowanie i limity czasu
Odpowiedzi strumieniowe (stream: true) są przesyłane jako Server-Sent Events. Ailoot zwraca płatną odpowiedź tekstową po obliczeniu kosztu. Dlatego przy stream: true format pozostaje strumieniowy (SSE), ale tekst jest przesyłany jednym blokiem po zakończeniu generowania przez model, a nie słowo po słowie. Jeśli przygotowanie odpowiedzi trwa dłużej niż około 15 sekund, w strumieniach Chat Completions, Responses i Messages najpierw pojawiają się wiersze techniczne : ping (mniej więcej co 10 sekund), następnie wiersz : ailoot-charged-usd … z pobraną kwotą i właściwe dane. SDK pomijają takie wiersze.
W formacie Gemini nie ma wierszy technicznych: odpowiedź :streamGenerateContent jest przesyłana w całości po obliczeniu kosztu. Dla modeli rozumujących ustaw limit czasu klienta z odpowiednim zapasem: kilka minut to normalny czas.
Nagłówki odpowiedzi
X-Request-ID jest dołączany do każdej odpowiedzi. Pozostałe nagłówki Ailoot dodaje do opłaconych odpowiedzi tekstowych:
| Nagłówek | Zawartość |
|---|---|
X-Request-ID | Identyfikator żądania — prosi o niego pomoc techniczna |
X-Ailoot-Charged-USD | Kwota pobrana za to żądanie, w dolarach |
X-Ailoot-Output-Tokens | Liczba opłaconych tokenów odpowiedzi |
X-Ailoot-Max-Tokens-Capped | Limit odpowiedzi po zmniejszeniu go z powodu salda niewystarczającego na pełną rezerwę |
X-Ailoot-Notice-Code, X-Ailoot-Notice | Wyjaśnienie, jeśli odpowiedź zakończyła się po osiągnięciu limitu długości |
Jeśli strumień rozpoczął się już od wierszy technicznych, te informacje są przekazywane jako wiersz komentarza przed danymi, a nie w nagłówku.
Pamięć podręczna promptów
Jeśli model obsługuje pamięć podręczną, ponowne wysłanie długiego prefiksu (instrukcji systemowej, dokumentów) może kosztować mniej. Ceny odczytu i zapisu pamięci podręcznej są podane na karcie modelu w katalogu. O tym, czy pamięć podręczna zostanie wykorzystana, decyduje twórca modelu; Ailoot tego nie gwarantuje.