Премини към основното съдържание
Български— Изберете език
Меню

Крайната точка /v1/chat/completions

Урок 1 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Вашият портал към моделите на Mistral
  2. Базовият URL
  3. Анатомия на заявката
  4. Еквивалент в Python със SDK
  5. Структура на отговора
  6. Чести кодове за грешки
  7. Ключови изводи

Актуализация от 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 в производствена среда.

1 крайна точка
За всички разговори
POST
Единствен HTTP метод
< 500 ms
Латентност на първия токен (поток)
JSON
Формат на вход/изход

Базовият 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
  • Токените за употреба ви позволяват да изчислите разходите си прецизно