Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

/v1/chat/completions-päätepiste

Oppitunti 1 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Porttisi Mistral-malleihin
  2. Perus-URL
  3. Pyynnön anatomia
  4. Python-vastaava SDK:n kanssa
  5. Vastauksen rakenne
  6. Yleiset virhekoodit
  7. Keskeiset asiat

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 aliasta mistral-large-latest, joka osoittaa tällä hetkellä Mistral Large 3 -malliin sen virallisen spesifikaation mukaan (varmistettu 3. marraskuuta 2026). Vastaavasti mistral-medium-latest osoittaa Mistral Medium 3.5 -malliin. Nämä aliakset pysyvät voimassa 30. huhtikuuta 2027 saakka. Uusia projekteja varten testaa mistral-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ä.

1 päätepiste
Kaikkiin keskusteluihin
POST
Yksi HTTP-metodi
< 500 ms
Ensimmäisen tokenin viive (streaming)
JSON
Syötteen ja tulosteen muoto

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/completions on ainoa päätepiste, jota tarvitaan keskusteluvuorovaikutuksiin
  • Jokainen pyyntö vaatii model-kentän ja messages-taulukon
  • Vastaus sisältää aina choices, usage ja finish_reason -kentät
  • Python-SDK yksinkertaistaa kutsuja merkittävästi verrattuna curl:iin
  • Käyttötiedot (usage tokens) mahdollistavat kustannustesi tarkan laskemisen