Koncový bod /v1/chat/completions
Na tejto strane
Aktualizácia z 2. novembra 2026 — Modely. Modely Mistral Large 3 (
mistral-large-2512) a Mistral Medium 3.5 boli 31. októbra 2026 vyradené z prevádzky (deprecated) a úplne sa odstavia 30. apríla 2027. Ich nástupca, Mistral Large 4 (mistral-large-4), je vo verejnej predbežnej verzii od 6. októbra. Príklady v tomto kurze používajú aliasmistral-large-latest, ktorý aktuálne podľa oficiálnej špecifikácie (overené 3. novembra 2026) odkazuje na Mistral Large 3. Podobnemistral-medium-latestodkazuje na Mistral Medium 3.5. Tieto aliasy zostanú platné do 30. apríla 2027. Pre nové projekty otestujtemistral-large-4, ich určeného nástupcu.
Tvoja brána k modelom Mistral
Všetko, čo robíš s API Mistral, prechádza cez jedinú cestu: /v1/chat/completions. Toto je centrálne rozbočovač platformy, ktorý vybavuje všetky tvoje konverzačné interakcie s jazykovými modelmi. Či už buduješ interného chatbota pre podporu, extraktor, ktorý mení faktúry v PDF na riadky v databáze, alebo asistenta na písanie integrovaného do tvojho CMS, tieto tri zdanlivo odlišné aplikácie volajú presne ten istý koncový bod, len s inými správami a parametrami. Nemusíš sa učiť tri samostatné integrácie; stačí, ak zvládneš jednu.
Od apríla 2026 tento koncový bod denne vybaví miliardy požiadaviek po celom svete. Pochopenie jeho štruktúry je prvým krokom k využitiu modelov Mistral v prevádzke.
Základná URL
Všetky požiadavky na API Mistral začínajú na rovnakej základnej adrese:
https://api.mistral.ai/v1/chat/completions
Odošleš požiadavku POST s telom vo formáte JSON, ktoré obsahuje tvoje správy a parametre, a API vráti štruktúrovanú odpoveď JSON. Nie je potrebné otvárať relácie ani udržiavať stav na strane servera: každý volanie je samostatné.
Anatómia požiadavky
Najrýchlejší spôsob, ako overiť, či tvoj kľúč funguje, je odoslať minimálnu požiadavku priamo z terminálu pomocou curl:
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?"}
]
}'
Dve hlavičky sú povinné: Content-Type: application/json opisuje formát tela požiadavky a Authorization: Bearer <tvoj-kľúč> prenáša tvoju autentifikáciu. Samotné telo musí obsahovať aspoň dve polia: model, čo je identifikátor modelu, ktorý chceš použiť, a messages, pole nesúce konverzáciu.
Ekvivalent v Pythone pomocou SDK
Akonáhle prekročíš fázu testovania, nikto v prevádzke nepíše surové príkazy curl. Oficiálne SDK urobí rovnaké volanie len na pár riadkoch:
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 sa za teba postará o hlavičky, serializáciu JSON a parsovanie odpovede. Tiež automaticky rieši opakované pokusy pri dočasných chybách, čo ťa zbavuje potreby písať vlastnú logiku retry, keď špička v premávke spôsobí prechodný výpadok.
Štruktúra odpovede
Nezáleží na tom, ako API voláš, vždy vráti rovnaký 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
}
}
Tri polia si zaslúžia tvoju okamžitú pozornosť. choices je pole obsahujúce vygenerovanú odpoveď (alebo odpovede); tu nájdeš text, ktorý sa má zobraziť používateľovi. usage poskytuje počet tokenov pre vstup, výstup a celkový súčet, čo ti umožňuje sledovať reálne náklady každej funkcie, namiesto toho, aby si zistil výšku faktúry až na konci mesiaca. Nakoniec, finish_reason vysvetľuje, prečo model prestal: stop pri prirodzenom konci, length, keď limit tokenov odpoveď prerušil, alebo tool_calls, keď model požiada o vykonanie nástroja. Zhrnutie, ktoré končí v polovici vety, takmer nikdy nie je problémom modelu; je to dôsledok hodnoty finish_reason nastavenej na length, ktorú si nikto nevšimol.
Bežné chybové kódy
Keď sa niečo pokazí, API vráti štandardné HTTP kódy:
- 400 — Chybne vytvorená požiadavka (neplatný JSON, chýbajúci parameter)
- 401 — Neplatný alebo chýbajúci API kľúč
- 429 – Dosiahnutý limit rýchlosti (príliš veľa požiadaviek)
- 500 – Chyba servera (skús to znova o niekoľko sekúnd)
V Pythone SDK vyhadzuje typované výnimky, ktoré môžeš zachytiť. To ti umožňuje rozlíšiť medzi vypršaným kľúčom a dočasným preťažením a v každom prípade reagovať inak:
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 obaliť každé volanie týmto blokom už od svojho úplne prvého skriptu. V deň, keď bude tvoja aplikácia bežať bez dozoru, ti povie, čo zlyhalo, namiesto toho, aby sa potichu zastavila.
Kľúčové poznatky
- Koncový bod
/v1/chat/completionsje jediný potrebný pre konverzačné interakcie - Každá požiadavka vyžaduje parameter
modela polemessages - Odpoveď vždy obsahuje
choices,usageafinish_reason - Python SDK výrazne zjednodušuje volania v porovnaní s
curl - Tokeny využitia ti umožňujú presne vypočítať tvoje náklady