Крайната точка /v1/chat/completions
На тази страница
Актуализация от 2 ноември 2026 г. — Модели. Mistral Large 3 (
mistral-large-2512) и Mistral Medium 3.5 бяха обявени за остарели на 31 октомври 2026 г. и ще бъдат изтеглени от употреба на 30 април 2027 г. Тяхният определен наследник, Mistral Large 4 (mistral-large-4), е в публичен преглед от 6 октомври. Примерите в този курс използват псевдонимаmistral-large-latest, който към момента сочи към Mistral Large 3 съгласно неговата официална спецификация (проверено на 3 ноември 2026 г.). По подобен начин,mistral-medium-latestсочи към Mistral Medium 3.5. Тези псевдоними ще останат валидни до 30 април 2027 г. За нови проекти тествайтеmistral-large-4, техния определен наследник.
Вашият портал към моделите на Mistral
Всичко, което правите с API на Mistral, минава през един единствен път: /v1/chat/completions. Това е централният хъб на платформата, обработващ всички ваши разговорни взаимодействия с езикови модели. Независимо дали изграждате вътрешен чатбот за поддръжка, екстрактор, който превръща PDF фактури в редове от база данни, или асистент за писане, интегриран във вашата CMS, тези три привидно различни приложения извикват точно същата крайна точка с различни съобщения и параметри. Не е необходимо да научавате три отделни интеграции; трябва само да овладеете една.
Към април 2026 г. тази крайна точка обработва милиарди заявки дневно по целия свят. Разбирането на нейната структура е първата стъпка към използването на моделите на Mistral в производствена среда.
Базовият URL
Всички заявки към API на Mistral започват от една и съща основа:
https://api.mistral.ai/v1/chat/completions
Изпращате POST заявка с JSON тяло, съдържащо вашите съобщения и параметри, а API връща структуриран JSON отговор. Няма сесии за отваряне и няма състояние на сървъра, което да поддържате: всяко извикване е самостоятелно.
Анатомия на заявката
Най-бързият начин да проверите дали вашият ключ работи, е да изпратите минимална заявка, използвайки curl директно от вашия терминал:
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?"}
]
}'
Два хедера са задължителни: Content-Type: application/json описва формата на тялото на заявката, а Authorization: Bearer <your-key> носи вашето удостоверяване. Самото тяло трябва да съдържа поне две полета: model – идентификаторът на модела за използване, и messages – масивът, носещ разговора.
Еквивалент в Python със SDK
След като преминете фазата на тестване, никой не пише сурови команди curl в производствена среда. Официалният SDK прави същото извикване само с няколко реда код:
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 обработва хедерите, JSON сериализацията и парсирането на отговора вместо вас. Той също така управлява автоматични повторни опити при временни грешки, спестявайки ви писането на собствена логика за повторни опити, когато скок в трафика причини преходен срив.
Структура на отговора
Независимо как извиквате API, той винаги връща един и същ 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
}
}
Три полета заслужават вашето незабавно внимание. choices е масив, съдържащ генерирания отговор (или отговори); тук намирате текста за показване на потребителя. usage предоставя броя токени за вход, изход и общия брой, позволявайки ви да проследявате реалната цена на всяка функция, вместо да откривате сметката в края на месеца. Накрая, finish_reason обяснява защо моделът е спрял: stop за естествен край, length, когато лимитът на токените е прекъснал отговора, или tool_calls, когато моделът поиска изпълнение на инструмент. Обобщение, което завършва по средата на изречението, почти никога не е проблем на модела; това е finish_reason със стойност length, който никой не е прочел.
Чести кодове за грешки
Когато нещо се обърка, API връща стандартни HTTP кодове:
- 400 — Неправилен формат на заявката (невалиден JSON, липсващ параметър)
- 401 — Невалиден или липсващ API ключ
- 429 — Достигнат лимит на честотата (твърде много заявки)
- 500 — Сървърна грешка (опитайте отново след няколко секунди)
В Python SDK поражда типизирани изключения, които можете да уловите, позволявайки ви да разграничите изтекъл ключ от временно претоварване и да реагирате различно във всеки случай:
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}")
Направете си навик да обгръщате всяко извикване в този блок още от първия си скрипт. В деня, в който вашето приложение работи без надзор, то ще ви каже какво се е объркало, вместо да спре тихо.
Ключови изводи
- Крайната точка
/v1/chat/completionsе единствената, необходима за разговорни взаимодействия - Всяка заявка изисква
modelи масивmessages - Отговорът винаги съдържа
choices,usageиfinish_reason - Python SDK значително опростява извикванията в сравнение с
curl - Токените за употреба ви позволяват да изчислите разходите си прецизно