Przegląd

Endpointy

Każdy endpoint znajduje się pod jednym base URL i jest obsługiwany przez HTTPS.

https://api.shannon-ai.com

Trzy endpointy generujące tekst docierają do tych samych modeli. Wybierz ten, którego formatu już używa Twój kod.

Podstawy zapytań

• Treść każdego POST to jeden obiekt JSON, do 32 MiB.
• Pole, którego API nie zna, nie powoduje błędu i nie ma żadnego skutku. Zapytanie napisane dla innego dostawcy nie kończy się niepowodzeniem z powodu dodatkowego pola.
• Znane pole z błędnym typem JSON albo brakujące wymagane pole dostaje odpowiedź 422. Treść, która nie jest poprawnym JSON, dostaje odpowiedź 400.
• model to jedno z id na stronie Models & pricing. Wielkość liter nie ma znaczenia.

Odpowiedź to JSON albo stream server-sent events, gdy zapytanie ustawia stream na true. Każdy endpoint odpowiada we własnym formacie. Każda odpowiedź ma nagłówek x-request-id.

Co zapytanie przechodzi

Zapytanie jest sprawdzane w stałej kolejności, zanim ruszy model. Odpowiada pierwsza kontrola, która się nie powiedzie, więc 401 nic jeszcze nie mówi o treści.

Kształt błędu

Błąd to obiekt JSON z polem error, które zawiera type i message. /v1/messages opakowuje go tak, jak oczekują SDK Anthropic; każda inna ścieżka używa kształtu OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Czytaj type i message. code i param występują tylko w niektórych błędach: traktuj je jako opcjonalne. param ma zawsze wartość null.
• Po rozpoczęciu streamu status to już 200. Awaria przychodzi wtedy jako ramka błędu wewnątrz streamu.
• Każda odpowiedź z błędem zawiera nagłówek x-request-id.

Obsługa błędów

Rozliczenia i saldo

• Na konto przypada jedno saldo, które współdzielą czat i API: najpierw dzisiejszy limit planu, potem zakupione środki. API nie ma własnego limitu.
• Zapytanie rezerwuje swój budżet wyjścia (max_tokens, domyślnie 4,096), a potem jest rozliczane za tokeny, które naprawdę zużyło, po cenie modelu.
• Każda odpowiedź podaje liczbę tokenów w usage. Strona Keys & usage pokazuje saldo i koszt każdego zapytania.
• Każde zapytanie jest obsługiwane jednakowo. Jedynym limitem tempa zapytań jest ochrona przed floodem: 120 zapytań na minutę na konto. Zapytania wysłane równolegle czekają w kolejce.

Limity i saldo Modele i ceny Keys & usage

Pola zależne od modelu

Każdy model przyjmuje to samo zapytanie. Kilka pól działa tylko w niektórych modelach; tabela podaje, w których. Strony endpointów wymieniają wszystkie pola.

Chat Completions

Jeśli przychodzisz z SDK OpenAI

• Ustaw base URL na https://api.shannon-ai.com/v1, a klucz na swój klucz Shannon. Wywołania Chat Completions i Responses działają wtedy z SDK bez zmian.
• model musi być id Shannon. Nazwa modelu innego dostawcy, na przykład gpt-4o, dostaje odpowiedź 400 i unknown model.
• Wnioskowanie ma własne pole: reasoning_content obok content, w wiadomości i w deltach streamu.
• Stream zawsze przekazuje usage w ostatnim chunku, razem z finish_reason.
• Wywołanie narzędzia w streamie przychodzi jako jeden chunk z kompletnym ciągiem arguments.
• Odpowiedź ma jeden choice.
• Ścieżki API OpenAI, których nie ma w tabeli powyżej, takie jak /v1/embeddings, dostają odpowiedź 404.

Jeśli przychodzisz z SDK Anthropic

• Ustaw base URL na https://api.shannon-ai.com, bez /v1, a klucz na swój klucz Shannon. SDK wysyła go jako x-api-key.
• model musi być id Shannon.
• max_tokens jest w tym API opcjonalne. Jego wartość domyślna to 4,096.
• Odpowiedź zawiera bloki treści typu thinking, text i tool_use. Pierwszy blok nie zawsze jest tekstem: wybieraj bloki według type.
• stop_reason to end_turn lub tool_use. Stream modelu Shannon może też skończyć się wartością max_tokens.
• anthropic-version i anthropic-beta są akceptowane, więc SDK działa bez zmian. Zapytanie ich nie potrzebuje.
• Błędy w /v1/messages mają kształt Anthropic: {"type": "error", "error": {…}}.

Narzędzia do kodowania, które mówią tymi formatami, konfiguruje się tak samo: base URL, klucz i id Shannon jako model. Narzędzia CLI do programowania