Koncový bod /v1/chat/completions
Na této stránce
Aktualizace 2. listopadu 2026 — Modely. Mistral Large 3 (
mistral-large-2512) a Mistral Medium 3.5 byly 31. října 2026 vyřazeny z provozu a budou zcela odstaveny 30. dubna 2027. Jejich nástupce, Mistral Large 4 (mistral-large-4), je ve veřejném náhledu od 6. října. Příklady v tomto kurzu používají aliasmistral-large-latest, který podle oficiální specifikace aktuálně odkazuje na Mistral Large 3 (ověřeno 3. listopadu 2026). Podobněmistral-medium-latestodkazuje na Mistral Medium 3.5. Tyto aliasy zůstanou platné až do 30. dubna 2027. Pro nové projekty otestujtemistral-large-4, jejich určeného nástupce.
Tvá brána k modelům Mistral
Všechno, co s API Mistral děláš, prochází jedinou cestou: /v1/chat/completions. To je centrální rozbočovač celé platformy, který zpracovává všechny tvé konverzační interakce s jazykovými modely. Ať už stavíš interního chatbota pro podporu, extraktor, který mění faktury v PDF na řádky v databázi, nebo asistenta pro psaní integrovaného do tvého CMS, všechny tyto tři zdánlivě odlišné aplikace volají přesně stejný koncový bod, jen s jinými zprávami a parametry. Nemusíš se učit tři samostatné integrace; stačí ti ovládnout jednu.
Od dubna 2026 tento koncový bod denně zpracovává miliardy požadavků po celém světě. Pochopení jeho struktury je prvním krokem k nasazení modelů Mistral do produkce.
Základní URL
Všechny požadavky na API Mistral vycházejí ze stejného základu:
https://api.mistral.ai/v1/chat/completions
Odešleš požadavek POST s tělem ve formátu JSON obsahujícím tvé zprávy a parametry a API vrátí strukturovanou odpověď JSON. Není třeba otevírat žádné relace ani udržovat stav na straně serveru: každý volání je soběstačné.
Anatomie požadavku
Nejrychlejší způsob, jak ověřit, že tvůj klíč funguje, je odeslat minimální požadavek pomocí curl přímo z terminálu:
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?"}
]
}'
Dvě hlavičky jsou povinné: Content-Type: application/json popisuje formát těla požadavku a Authorization: Bearer <tvůj-klíč> přenáší tvé ověření. Samotné tělo musí obsahovat alespoň dvě pole: model, identifikátor modelu, který chceš použít, a messages, pole nesoucí konverzaci.
Ekvivalent v Pythonu pomocí SDK
Jakmile překonáš fázi testování, nikdo v produkci nepíše surové příkazy curl. Oficiální SDK provede stejné volání jen v několika řádcích:
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 se za tebe postará o hlavičky, serializaci JSON a parsování odpovědi. Také automaticky řeší opakované pokusy při dočasných chybách, takže nemusíš psát vlastní logiku pro retry, když špička provozu způsobí přechodný výpadek.
Struktura odpovědi
Ať už API voláš jakkoli, vždy vrátí stejný objekt 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
}
}
Tři pole si zaslouží tvou okamžitou pozornost. choices je pole obsahující vygenerovanou odpověď (nebo odpovědi); zde najdeš text k zobrazení uživateli. usage poskytuje počet tokenů pro vstup, výstup a celkem, což ti umožňuje sledovat skutečné náklady každé funkce, místo abys účet objevil až na konci měsíce. Nakonec, finish_reason vysvětluje, proč model přestal: stop pro přirozený konec, length, když limit tokenů odpověď uřízl, nebo tool_calls, když model požaduje spuštění nástroje. Shrnutí, které končí uprostřed věty, téměř nikdy není problém modelu; je to důsledek finish_reason s hodnotou length, který nikdo nečetl.
Běžné chybové kódy
Když se něco pokazí, API vrátí standardní HTTP kódy:
- 400 — Chybně vytvořený požadavek (neplatný JSON, chybějící parametr)
- 401 — Neplatný nebo chybějící API klíč
- 429 – Dosažen limit rychlosti (příliš mnoho požadavků)
- 500 — Chyba serveru (zkus to znovu za pár sekund)
V Pythonu SDK vyvolává typované výjimky, které můžeš zachytit. To ti umožňuje rozlišit mezi vypršelým klíčem a dočasným přetížením a v každém případě reagovat odlišně:
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}")
Zvykni si obalit každé volání tímto blokem už ve svém úplně prvním skriptu. Až bude tvá aplikace běžet bez dozoru, řekne ti, co selhalo, místo aby tiše skončila.
Klíčové poznatky
- Koncový bod
/v1/chat/completionsje jediný potřebný pro konverzační interakce - Každý požadavek vyžaduje
modela polemessages - Odpověď vždy obsahuje
choices,usageafinish_reason - Python SDK výrazně zjednodušuje volání oproti
curl - Tokeny využití ti umožní přesně vypočítat tvé náklady