Salt la conținutul principal
Română— Alege o limbă
Meniu

Endpointul /v1/chat/completions

Lecția 1 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Poarta dumneavoastră către modelele Mistral
  2. URL-ul de bază
  3. Anatomia unei cereri
  4. Echivalentul în Python cu SDK-ul
  5. Structura răspunsului
  6. Coduri de eroare comune
  7. Puncte cheie

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ă aliasul mistral-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-latest indică către Mistral Medium 3.5. Aceste aliasuri vor rămâne valabile până la 30 aprilie 2027. Pentru proiecte noi, testați mistral-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.

1 endpoint
Pentru toate conversațiile
POST
O singură metodă HTTP
< 500 ms
Latența primului token (streaming)
JSON
Format intrare/ieșire

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/completions este singurul necesar pentru interacțiunile conversaționale
  • Fiecare cerere necesită un model și un tablou messages
  • Răspunsul conține întotdeauna choices, usage și finish_reason
  • SDK-ul Python simplifică semnificativ apelurile comparativ cu curl
  • Tokenii de utilizare vă permit să calculați costurile cu precizie