/v1/chat/completions-päätepiste
Tällä sivulla
Päivitys 2. marraskuuta 2026 — Mallit. Mistral Large 3 (
mistral-large-2512) ja Mistral Medium 3.5 poistettiin käytöstä 31. lokakuuta 2026, ja ne poistetaan kokonaan 30. huhtikuuta 2027. Niiden nimetty seuraaja, Mistral Large 4 (mistral-large-4), on ollut julkisessa esiversiossa 6. lokakuuta lähtien. Tämän kurssin esimerkeissä käytetään aliastamistral-large-latest, joka osoittaa tällä hetkellä Mistral Large 3 -malliin sen virallisen spesifikaation mukaan (varmistettu 3. marraskuuta 2026). Vastaavastimistral-medium-latestosoittaa Mistral Medium 3.5 -malliin. Nämä aliakset pysyvät voimassa 30. huhtikuuta 2027 saakka. Uusia projekteja varten testaamistral-large-4:ää, niiden nimettyä seuraajaa.
Porttisi Mistral-malleihin
Kaikki Mistral API:n kanssa tekemäsi kulkee yhden polun kautta: /v1/chat/completions. Tämä on alustan keskeinen solmukohta, joka hoitaa kaikki keskusteluvuorovaikutuksesi kielimallien kanssa. Rakennitpa sitten sisäistä tukichattibottia, laskuja tietokantariveiksi muuntavaa erottajaa tai CMS-järjestelmään integroitua kirjoitusapuria, nämä kolme näennäisesti erilaista sovellusta kutsuvat täsmälleen samaa päätepistettä eri viesteillä ja parametreilla. Sinun ei tarvitse opetella kolmea erillistä integraatiota; sinun tarvitsee vain hallita yksi.
Huhtikuuhun 2026 mennessä tämä päätepiste käsittelee miljardeja pyyntöjä päivittäin maailmanlaajuisesti. Sen rakenteen ymmärtäminen on ensimmäinen askel Mistral-mallien hyödyntämiseen tuotantoympäristössä.
Perus-URL
Kaikki Mistral API:n pyynnöt alkavat samasta perusosoitteesta:
https://api.mistral.ai/v1/chat/completions
Lähetät POST-pyynnön, jonka JSON-runko sisältää viestisi ja parametrinsi, ja API palauttaa jäsennellyn JSON-vastauksen. Istuntoja ei tarvitse avata eikä palvelinpuolen tilaa ylläpitää: jokainen kutsu on itsenäinen.
Pyynnön anatomia
Nopein tapa varmistaa avaimesi toimivuus on lähettää minimaalinen pyyntö käyttämällä curl:ia suoraan päätteesi kautta:
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?"}
]
}'
Kaksi otsikkoa ovat pakollisia: Content-Type: application/json määrittelee pyynnön rungon muodon, ja Authorization: Bearer <your-key> välittää tunnistautumisesi. Itse rungon on sisällettävä vähintään kaksi kenttää: model, joka on käytettävän mallin tunniste, ja messages, joka on keskustelua kantava taulukko.
Python-vastaava SDK:n kanssa
Kun testausvaihe on ohi, kukaan ei kirjoita raakoja curl-komentoja tuotantoympäristössä. Virallinen SDK tekee saman kutsun vain muutamalla rivillä:
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 hoitaa puolestasi otsikot, JSON-sarjoituksen ja vastauksen jäsentämisen. Se hallinnoi myös automaattisia uudelleenyrityksiä tilapäisten virheiden varalta, säästäen sinut oman uudelleenyrityslogiikan kirjoittamiselta, kun liikennepiikki aiheuttaa ohimenevän vian.
Vastauksen rakenne
Riippumatta siitä, miten kutsut API:a, se palauttaa aina saman JSON-objektin:
{
"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
}
}
Kolme kenttää ansaitsevat välittömän huomiosi. choices on taulukko, joka sisältää generoidun vastauksen (tai vastaukset); täältä löydät käyttäjälle näytettävän tekstin. usage tarjoaa token-määrät syötteelle, tulosteelle ja kokonaismäärälle, jolloin voit seurata kunkin ominaisuuden todellista kustannusta sen sijaan, että huomaisit laskun vasta kuukauden lopussa. Lopuksi finish_reason selittää, miksi malli pysähtyi: stop tarkoittaa luonnollista loppua, length tarkoittaa, että token-raja katkaisi vastauksen, tai tool_calls tarkoittaa, että malli pyytää työkalun suorittamista. Lauseen keskellä päättyvä yhteenveto ei lähes koskaan ole mallin vika; se on finish_reason arvo length, jota kukaan ei lukenut.
Yleiset virhekoodit
Kun jotain menee pieleen, API palauttaa standardit HTTP-koodit:
- 400 — Virheellinen pyyntö (virheellinen JSON, puuttuva parametri)
- 401 – Virheellinen tai puuttuva API-avain
- 429 – Nopeusrajoitus saavutettu (liian monta pyyntöä)
- 500 – Palvelinvirhe (yritä uudelleen muutaman sekunnin kuluttua)
Pythonissa SDK nostaa tyypitettyjä poikkeuksia, jotka voit siepata. Tämä mahdollistaa erottelun vanhentuneen avaimen ja tilapäisen ylikuormituksen välillä, jolloin voit reagoida eri tavoin kussakin tapauksessa:
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}")
Tee tavaksi kääriä jokainen kutsu tähän lohkoon jo ensimmäisestä skriptistäsi lähtien. Sinä päivänä, kun sovelluksesi toimii ilman valvontaa, se kertoo sinulle, mikä epäonnistui, sen sijaan että pysähtyisi hiljaa.
Keskeiset asiat
/v1/chat/completionson ainoa päätepiste, jota tarvitaan keskusteluvuorovaikutuksiin- Jokainen pyyntö vaatii
model-kentän jamessages-taulukon - Vastaus sisältää aina
choices,usagejafinish_reason-kentät - Python-SDK yksinkertaistaa kutsuja merkittävästi verrattuna
curl:iin - Käyttötiedot (usage tokens) mahdollistavat kustannustesi tarkan laskemisen