A /v1/chat/completions végpont
Ezen az oldalon
Frissítés: 2026. november 2. — Modellek. A Mistral Large 3 (
mistral-large-2512) és a Mistral Medium 3.5 modelleket 2026. október 31-én elavulttá nyilvánították, és 2027. április 30-án végleg kivezetik őket. A kijelölt utódjuk, a Mistral Large 4 (mistral-large-4) már október 6. óta elérhető nyilvános előzetes verzióban. Az ebben a tananyagban szereplő példák amistral-large-latestálnevet használják, amely a hivatalos specifikáció szerint jelenleg a Mistral Large 3-ra mutat (ellenőrizve: 2026. november 3.). Hasonlóképpen, amistral-medium-latestalias a Mistral Medium 3.5-re hivatkozik. Ezek az álnevek 2027. április 30-ig érvényesek maradnak. Új projektek esetén teszteld a kijelölt utódot, amistral-large-4modellt.
A kapud a Mistral modellekhez
A Mistral API-val végzett minden művelet egyetlen útvonalon keresztül zajlik: /v1/chat/completions. Ez a platform központi csomópontja, amely kezeli az összes nyelvi modellel folytatott beszélgetésedet. Legyen szó belső ügyfélszolgálati chatbotról, PDF-számlákat adatbázis-sorokká alakító kinyerő eszközről, vagy a CMS-edbe integrált írási asszisztensről, ez a három látszólag különböző alkalmazás pontosan ugyanazt a végpontot hívja meg, csupán eltérő üzenetekkel és paraméterekkel. Nem kell három külön integrációt megtanulnod; elég, ha egyetlenegyben válsz jártassá.
2026 áprilisa óta ez a végpont naponta milliárdnyi kérést kezel világszerte. A szerkezetének megértése az első lépés ahhoz, hogy éles környezetben is sikeresen alkalmazd a Mistral modelleket.
Az alapURL
A Mistral API-hoz intézett összes kérés ugyanabból az alapcímből indul:
https://api.mistral.ai/v1/chat/completions
Egy POST kérést küldesz egy JSON törzzsel, amely tartalmazza az üzeneteidet és a paramétereidet, mire az API egy strukturált JSON választ ad vissza. Nincsenek megnyitandó munkamenetek, és nincs szerveroldali állapot, amit维持en kellene: minden hívás önmagában teljes.
Egy kérés felépítése
A leggyorsabb módja annak, hogy ellenőrizd a kulcsod működőképességét, ha egy minimális kérést küldesz közvetlenül a terminálodból curl segítségével:
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?"}
]
}'
Két fejléc kötelező: a Content-Type: application/json leírja a kérés törzsének formátumát, az Authorization: Bearer <a-kulcsod> pedig továbbítja a hitelesítésedet. Magának a törzsnek legalább két mezőt kell tartalmaznia: a model-t, amely a használni kívánt modell azonosítója, és a messages tömböt, amely a beszélgetést hordozza.
Python megfelelő az SDK-val
Amint túljutsz a tesztelési fázison, senki nem ír nyers curl parancsokat éles környezetben. A hivatalos SDK ugyanazt a hívást mindössze néhány sorral végrehajtja:
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)
Az SDK elvégzi helyetted a fejlécek kezelését, a JSON szerializálást és a válasz feldolgozását. Emellett kezeli az ideiglenes hibák miatti automatikus újrapróbálkozásokat is, így megspórolod saját retry logika megírását, amikor egy forgalmi csúcs átmeneti hibát okoz.
A válasz szerkezete
Függetlenül attól, hogyan hívod meg az API-t, az mindig ugyanazt a JSON objektumot adja vissza:
{
"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
}
}
Három mező azonnali figyelmet érdemel. A choices egy tömb, amely a generált választ (vagy válaszokat) tartalmazza; itt találod a felhasználónak megjelenítendő szöveget. A usage megadja a bemeneti, kimeneti és teljes tokenek számát, lehetővé téve, hogy nyomon kövesd az egyes funkciók valós költségét, ahelyett, hogy csak a hónap végén szembesülnél a számlával. Végül a finish_reason megmagyarázza, miért állt le a modell: stop természetes befejezés esetén, length, ha a tokenlimit levágta a választ, vagy tool_calls, ha a modell eszközvégrehajtást kér. Egy mondat közepén végződő összefoglaló szinte sosem modellhiba; ez egy length típusú finish_reason, amit senki sem olvasott el.
Gyakori hibakódok
Amikor valami hiba történik, az API szabványos HTTP kódokat ad vissza:
- 400 — Rosszul formázott kérés (érvénytelen JSON, hiányzó paraméter)
- 401 — Érvénytelen vagy hiányzó API-kulcs
- 429 — Elért sebességkorlát (túl sok kérés)
- 500 — Szerverhiba (próbáld újra néhány másodperc múlva)
Pythonban az SDK típusozott kivételeket dob, amelyeket elkapvhatsz, így különbséget tehetsz egy lejárt kulcs és egy ideiglenes túlterheltség között, és eszerint reagálhatsz:
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}")
Szoktasd rá magad, hogy már az első szkriptedtől kezdve minden hívást ebbe a blokkba csomagolsz. Amikor az alkalmazásod felügyelet nélkül fut, ez a blokk fogja megmondani, mi ment tönkre, ahelyett, hogy csendben leállna.
Főbb megállapítások
- A
/v1/chat/completionsvégpont az egyetlen, amelyre a beszélgetés alapú interakciókhoz szükség van - Minden kéréshez szükséges egy
modelés egymessagestömb - A válasz mindig tartalmaz
choices,usageésfinish_reasonmezőket - A Python SDK jelentősen leegyszerűsíti a hívásokat a
curl-hoz képest - A használati tokenek lehetővé teszik a költségek pontos kiszámítását