Przewodnik wdrożeniowy
Modele tekstowe mówią tu protokołami, które twój SDK już zna: Chat Completions, bezstanowy podzbiór Responses, Anthropic Messages i generateContent od Google. Ciekawe pytanie brzmi, co dzieje się z parametrem, którego docelowy model nigdy nie zadeklarował.
Wyzwanie
Klasyczna awaria to nie jest 500. To parametr, który twoja brama przyjęła, odrzuciła i nigdy o tym nie wspomniała, więc model pracował bez twojego temperature, bez twoich definicji narzędzi albo bez twojego formatu odpowiedzi – a wynik wyglądał tylko na rozczarowujący, nie na zepsuty.
01
messages, tools, tool_choice, response_format, max_tokens, temperature i top_p mapują się na pola deklarowane przez model. Wszystko inne trafia do schematu modelu i kończy się kodem 400, gdy model tego nie deklaruje. Milczenie nigdy nie jest odpowiedzią.
02
Na /v1 treść jest obiektem błędu w stylu OpenAI albo Anthropic, a nie strukturą {code, msg, data, request_id} używaną przez /api/v1. Obsłuż obie, jeśli twój produkt miesza te powierzchnie.
03
stream: true zwraca zdarzenia chat.completion.chunk zamknięte przez data: [DONE]. Rozliczenie i tak idzie za zmierzonym zużyciem, więc przerwany strumień nie jest darmowym żądaniem.
Podejście
Zmień base_url i api_key, podmień nazwę modelu na wartość z GET /v1/models i uruchom zestaw testów, który już masz. Tam, gdzie wraca 400 na parametrze, ten parametr nigdy nie był obsługiwany przez wybrany model – a tej informacji cicha wersja nie dawała.
Zadziała każdy klient zgodny z OpenAI. Zmienia się tylko bazowy adres i wartość model.
POST /v1/chat/completions
from openai import OpenAI
client = OpenAI(
base_url="https://api.spicyapi.ai/v1",
api_key=os.environ["SPICY_API_KEY"],
)
stream = client.chat.completions.create(
model="<publisher>/<model>/chat", # exact value from GET /v1/models
messages=[{"role": "user", "content": "Summarise these notes in three bullets."}],
temperature=0.7,
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")text/event-stream
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"- "}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Ships"}}]}
data: [DONE]Kontrakt
| Pole lub nagłówek | Wartość lub limit |
|---|---|
| POST /v1/chat/completions | chat.completion · SSE with stream: true |
| GET /v1/models | every callable model value |
| Authorization: Bearer · x-api-key · x-goog-api-key | accepted on /v1 |
| undeclared parameter | 400 · never silently dropped |
Przesuń w poziomie, żeby zobaczyć wszystkie kolumny.
Integracja
Dopasowanie
Dowody
/v1/chat/completions, /v1/responses, /v1/messages i /v1beta/models/{model}:generateContent uwierzytelniają się tym samym kluczem. Authorization: Bearer, x-api-key i x-goog-api-key przyjmujemy każdy tam, gdzie spodziewa się go SDK.
GET /v1/models zwraca dokładnie te identyfikatory, które przyjmuje każda operacja /v1 i /api/v1, a w owned_by podaje twórcę modelu. Ceny pochodzą z /api/v1/models, które jest zależne od konta i przez to prywatne.
Warstwa zgodności korzysta z tego samego uwierzytelniania, tych samych limitów żądań, walidacji, cen i logiki blokad co powierzchnia natywna. Różni się tylko struktura odpowiedzi.
Przed startem
FAQ
Modele
Każdy odnośnik prowadzi na stronę danej rodziny modeli: wejścia, limity, zasady dotyczące treści i aktualna cena za jednostkę.
Co dalej
Skieruj istniejącego klienta OpenAI, Anthropic albo Google na SpicyAPI. Co przechodzi wprost, co odrzucamy celowo i jak rozliczamy tekst.
