Endpointul /v1/chat/completions
Pe această pagină
Actualizare 2 noiembrie 2026 — Modele. Mistral Large 3 (
mistral-large-2512) și Mistral Medium 3.5 au fost depreciate la 31 octombrie 2026 și vor fi retrase la 30 aprilie 2027. Succesorul lor desemnat, Mistral Large 4 (mistral-large-4), se află în previzualizare publică din 6 octombrie. Exemplele din acest curs utilizează aliasulmistral-large-latest, care indică în prezent către Mistral Large 3 conform specificației oficiale (verificat la 3 noiembrie 2026). În mod similar,mistral-medium-latestindică către Mistral Medium 3.5. Aceste aliasuri vor rămâne valabile până la 30 aprilie 2027. Pentru proiecte noi, testațimistral-large-4, succesorul lor desemnat.
Poarta dumneavoastră către modelele Mistral
Tot ceea ce faceți cu API-ul Mistral trece printr-o singură cale: /v1/chat/completions. Acesta este hub-ul central al platformei, gestionând toate interacțiunile conversaționale cu modelele lingvistice. Fie că construiți un chatbot intern de suport, un extractor care transformă facturile PDF în rânduri de bază de date sau un asistent de scriere integrat în CMS-ul dumneavoastră, aceste trei aplicații aparent diferite apelează exact același endpoint, dar cu mesaje și parametri diferiți. Nu trebuie să învățați trei integrări separate; trebuie doar să stăpâniți una singură.
Începând cu aprilie 2026, acest endpoint gestionează miliarde de cereri zilnic la nivel mondial. Înțelegerea structurii sale este primul pas pentru utilizarea modelelor Mistral în producție.
URL-ul de bază
Toate cererile către API-ul Mistral pornesc de la aceeași bază:
https://api.mistral.ai/v1/chat/completions
Trimiteți o cerere POST cu un corp JSON conținând mesajele și parametrii dumneavoastră, iar API-ul returnează un răspuns JSON structurat. Nu există sesiuni de deschis și nici stare de server de menținut: fiecare apel este autonom.
Anatomia unei cereri
Cea mai rapidă modalitate de a verifica dacă cheia dumneavoastră funcționează este să trimiteți o cerere minimă folosind curl direct din terminal:
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?"}
]
}'
Două antete sunt obligatorii: Content-Type: application/json descrie formatul corpului cererii, iar Authorization: Bearer <your-key> transmite autentificarea dumneavoastră. Corpul în sine trebuie să conțină cel puțin două câmpuri: model, identificatorul modelului de utilizat, și messages, tabloul care poartă conversația.
Echivalentul în Python cu SDK-ul
Odată ce treceți de faza de testare, nimeni nu scrie comenzi curl brute în producție. SDK-ul oficial realizează același apel în doar câteva linii:
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-ul gestionează antetele, serializarea JSON și analizarea răspunsului pentru dumneavoastră. De asemenea, gestionează reîncercările automate pentru erorile temporare, scutindu-vă de scrierea propriei logici de reîncercare atunci când un vârf de trafic provoacă o defecțiune tranzitorie.
Structura răspunsului
Indiferent cum apelați API-ul, acesta returnează întotdeauna același obiect 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
}
}
Trei câmpuri merită atenția dumneavoastră imediată. choices este un tablou conținând răspunsul (răspunsurile) generat(e); aici găsiți textul de afișat utilizatorului. usage oferă numărul de tokeni pentru intrare, ieșire și total, permițându-vă să urmăriți costul real al fiecărei funcționalități, în loc să descoperiți factura la sfârșitul lunii. În final, finish_reason explică de ce s-a oprit modelul: stop pentru o încheiere naturală, length când limita de tokeni a întrerupt răspunsul, sau tool_calls când modelul solicită executarea unor instrumente. Un rezumat care se termină la mijlocul unei propoziții nu este aproape niciodată o problemă a modelului; este un finish_reason de tip length pe care nimeni nu l-a citit.
Coduri de eroare comune
Când ceva nu merge bine, API-ul returnează coduri HTTP standard:
- 400 — Cerere malformată (JSON invalid, parametru lipsă)
- 401 — Cheie API invalidă sau lipsă
- 429 — Limită de rată atinsă (prea multe cereri)
- 500 — Eroare de server (reîncercați după câteva secunde)
În Python, SDK-ul ridică excepții tipizate pe care le puteți prinde, permițându-vă să distingeți între o cheie expirată și o saturație temporară, reacționând diferit în fiecare caz:
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}")
Obișnuiți-vă să încadrați fiecare apel în acest bloc încă de la primul dumneavoastră script. În ziua în care aplicația dumneavoastră rulează nesupravegheată, aceasta vă va spune ce a eșuat în loc să se oprească în tăcere.
Puncte cheie
- Endpointul
/v1/chat/completionseste singurul necesar pentru interacțiunile conversaționale - Fiecare cerere necesită un
modelși un tabloumessages - Răspunsul conține întotdeauna
choices,usageșifinish_reason - SDK-ul Python simplifică semnificativ apelurile comparativ cu
curl - Tokenii de utilizare vă permit să calculați costurile cu precizie