Punkt końcowy /v1/chat/completions
Na tej stronie
Aktualizacja z 2 listopada 2026 r. — Modele. Mistral Large 3 (
mistral-large-2512) i Mistral Medium 3.5 zostały wycofane z użytku (deprecated) 31 października 2026 r. i zostaną całkowicie usunięte (retired) 30 kwietnia 2027 r. Ich wyznaczony następca, Mistral Large 4 (mistral-large-4), jest dostępny w wersji publicznej (public preview) od 6 października. Przykłady w tym kursie używają aliasumistral-large-latest, który obecnie wskazuje na Mistral Large 3 zgodnie z jego oficjalną specyfikacją (zweryfikowano 3 listopada 2026 r.). Podobniemistral-medium-latestwskazuje na Mistral Medium 3.5. Aliasy te pozostaną ważne do 30 kwietnia 2027 r. W przypadku nowych projektów przetestujmistral-large-4, ich wyznaczonego następcę.
Twoja brama do modeli Mistral
Wszystko, co robisz z API Mistral, przechodzi przez jedną ścieżkę: /v1/chat/completions. To centralny punkt platformy, obsługujący wszystkie Twoje interakcje konwersacyjne z modelami językowymi. Niezależnie od tego, czy budujesz wewnętrznego chatbota wsparcia, ekstraktor zamieniający faktury PDF w wiersze bazy danych, czy asystenta pisania zintegrowanego z Twoim CMS, te trzy pozornie różne aplikacje wywołują dokładnie ten sam punkt końcowy, używając różnych wiadomości i parametrów. Nie musisz uczyć się trzech osobnych integracji; wystarczy, że opanujesz jedną.
Od kwietnia 2026 r. ten punkt końcowy obsługuje miliardy żądań dziennie na całym świecie. Zrozumienie jego struktury to pierwszy krok do wykorzystania modeli Mistral w środowisku produkcyjnym.
Bazowy URL
Wszystkie żądania do API Mistral zaczynają się od tej samej podstawy:
https://api.mistral.ai/v1/chat/completions
Wysyłasz żądanie POST z ciałem JSON zawierającym Twoje wiadomości i parametry, a API zwraca ustrukturyzowaną odpowiedź JSON. Nie ma tu sesji do otwierania ani stanu po stronie serwera do utrzymywania: każde wywołanie jest samodzielne.
Anatomia żądania
Najszybszym sposobem na sprawdzenie, czy Twój klucz działa, jest wysłanie minimalnego żądania za pomocą curl bezpośrednio z terminala:
curl https://api.mistral.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MISTRAL_API_KEY" \
-d '{
"model": "mistral-large-latest",
"messages": [
{"role": "user", "content": "Hello, how does your API work?"}
]
}'
Dwa nagłówki są obowiązkowe: Content-Type: application/json opisuje format ciała żądania, a Authorization: Bearer <twój-klucz> przenosi Twoją autentyfikację. Samo ciało musi zawierać co najmniej dwa pola: model, identyfikator modelu do użycia, oraz messages, tablicę przenoszącą konwersację.
Odpowiednik w Pythonie z użyciem SDK
Gdy tylko miniesz fazę testów, nikt nie pisze surowych poleceń curl w środowisku produkcyjnym. Oficjalne SDK pozwala wykonać to samo wywołanie w zaledwie kilku liniach:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Hello, how does your API work?"}
]
)
print(response.choices[0].message.content)
SDK zajmuje się nagłówkami, serializacją JSON i parsowaniem odpowiedzi za Ciebie. Zarządza również automatycznymi ponownymi próbami w przypadku błędów tymczasowych, oszczędzając Ci pisania własnej logiki retry, gdy skok ruchu powoduje przejściową awarię.
Struktura odpowiedzi
Niezależnie od tego, jak wywołujesz API, zawsze zwraca ono ten sam obiekt JSON:
{
"id": "cmpl-abc123",
"object": "chat.completion",
"created": 1712150400,
"model": "mistral-large-latest",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! The Mistral API works..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 15,
"completion_tokens": 87,
"total_tokens": 102
}
}
Trzy pola zasługują na Twoją natychmiastową uwagę. choices to tablica zawierająca wygenerowaną odpowiedź (lub odpowiedzi); to tutaj znajdziesz tekst do wyświetlenia użytkownikowi. usage podaje liczbę tokenów dla wejścia, wyjścia i sumy, co pozwala śledzić rzeczywisty koszt każdej funkcji, zamiast odkrywać rachunek na koniec miesiąca. Na koniec, finish_reason wyjaśnia, dlaczego model się zatrzymał: stop dla naturalnego końca, length, gdy limit tokenów uciął odpowiedź, lub tool_calls, gdy model żąda wykonania narzędzia. Podsumowanie, które urywa się w połowie zdania, prawie nigdy nie jest problemem modelu; to finish_reason wynoszący length, którego nikt nie przeczytał.
Typowe kody błędów
Gdy coś pójdzie nie tak, API zwraca standardowe kody HTTP:
- 400 — Źle sformatowane żądanie (nieprawidłowy JSON, brakujący parametr)
- 401 — Nieprawidłowy lub brakujący klucz API
- 429 — Osiągnięto limit częstotliwości (zbyt wiele żądań)
- 500 — Błąd serwera (spróbuj ponownie po kilku sekundach)
W Pythonie SDK zgłasza typowane wyjątki, które możesz przechwycić, pozwalając rozróżnić wygasły klucz od tymczasowego przeciążenia i zareagować inaczej w każdym przypadku:
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Test"}]
)
except SDKError as e:
print(f"API Error: {e.status_code} — {e.message}")
Wyrób sobie nawyk otaczania każdego wywołania tym blokiem już w pierwszym skrypcie. Dnia, gdy Twoja aplikacja będzie działać bez nadzoru, powie Ci, co zawiodło, zamiast cicho się zatrzymać.
Kluczowe wnioski
- Punkt końcowy
/v1/chat/completionsto jedyne miejsce potrzebne do interakcji konwersacyjnych - Każde żądanie wymaga pola
modeli tablicymessages - Odpowiedź zawsze zawiera
choices,usageifinish_reason - Python SDK znacznie upraszcza wywołania w porównaniu do
curl - Tokeny użycia pozwalają precyzyjnie obliczyć koszty