POST /chat/completions

Эндпоинт завершения чата является основным методом взаимодействия с языковыми моделями через API LLMost. Он позволяет отправлять сообщения и получать ответы от широкого спектра AI-моделей через единый интерфейс.

Основная информация

Эндпоинт: POST https://llmost.ru/api/v1/chat/completions

Этот эндпоинт совместим с OpenAI Chat Completion API, что позволяет легко мигрировать существующие приложения на LLMost, просто изменив базовый URL.

Совместимость с OpenAI SDK

LLMost полностью совместим с официальными SDK OpenAI для Python, JavaScript и других языков. Просто измените base_url на https://llmost.ru/api/v1 и используйте ваш API-ключ LLMost.

Быстрый старт

Базовый пример

const response = await fetch('https://llmost.ru/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <LLMOST_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'В чём смысл жизни?',
      },
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

Обязательные параметры

model

Тип: string

Идентификатор модели для использования. Должен включать префикс организации (например, openai/gpt-4o, anthropic/claude-3.5-sonnet).

Посмотрите полный список доступных моделей на странице Модели или через API моделей.

{
  "model": "openai/gpt-4o"
}

Модель по умолчанию

Если параметр model опущен, будет использована модель по умолчанию пользователя, установленная в настройках аккаунта.

messages

Тип: array

Массив сообщений, составляющих историю беседы. Каждое сообщение должно содержать роль и контент.

Поддерживаемые роли

system - Инструкции высокого уровня для модели
user - Сообщения от пользователя
assistant - Предыдущие ответы модели
tool - Результаты вызова инструментов

{
  "messages": [
    {
      "role": "system",
      "content": "Ты - полезный помощник по программированию."
    },
    {
      "role": "user",
      "content": "Как создать REST API на Node.js?"
    }
  ]
}

Опциональные параметры

temperature

Тип: number • Диапазон: [0, 2] • По умолчанию: 1

Контролирует случайность вывода. Более высокие значения делают вывод более случайным и креативным, более низкие значения делают его более сфокусированным и детерминированным.

{
  "temperature": 0.7
}

max_tokens

Тип: number • Диапазон: [1, context_length)

Максимальное количество токенов для генерации в ответе.

{
  "max_tokens": 500
}

stream

Тип: boolean • По умолчанию: false

Включить потоковую передачу ответа через Server-Sent Events. См. Потоковая передача для деталей.

{
  "stream": true
}

top_p

Тип: number • Диапазон: (0, 1] • По умолчанию: 1

Альтернатива температуре, называемая nucleus sampling. Модель рассматривает результаты токенов с вероятностной массой top_p.

{
  "top_p": 0.9
}

frequency_penalty

Тип: number • Диапазон: [-2, 2] • По умолчанию: 0

Штрафует повторяющиеся токены на основе частоты их появления. Положительные значения снижают вероятность повторения.

{
  "frequency_penalty": 0.5
}

presence_penalty

Тип: number • Диапазон: [-2, 2] • По умолчанию: 0

Штрафует токены, которые уже появились в тексте. Побуждает модель говорить о новых темах.

{
  "presence_penalty": 0.6
}

stop

Тип: string | string[]

До 4 последовательностей, при которых API прекратит генерацию дополнительных токенов.

{
  "stop": ["\n", "User:", "Assistant:"]
}

Полный список параметров см. на странице Параметры.

Структура ответа

Успешный ответ

{
  "id": "gen-1234567890",
  "model": "openai/gpt-4o",
  "object": "chat.completion",
  "created": 1234567890,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Смысл жизни - философский вопрос..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 120,
    "total_tokens": 135
  }
}

Поля ответа

choices

Массив вариантов ответа. По умолчанию содержит один элемент.

message - Сообщение, сгенерированное моделью
finish_reason - Причина остановки генерации:
- stop - Естественная остановка или достигнута stop-последовательность
- length - Достигнут лимит max_tokens
- content_filter - Контент был отфильтрован
- tool_calls - Модель хочет вызвать инструмент
- error - Произошла ошибка

usage

Информация об использовании токенов.

prompt_tokens - Количество токенов в запросе
completion_tokens - Количество токенов в ответе
total_tokens - Общее количество токенов

Примеры кода

Python с OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://llmost.ru/api/v1",
    api_key="ВАШ_API_КЛЮЧ",
)

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "Ты - эксперт по Python."
        },
        {
            "role": "user",
            "content": "Объясни декораторы в Python"
        }
    ],
    temperature=0.7,
    max_tokens=500
)

print(completion.choices[0].message.content)

TypeScript с OpenAI SDK

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://llmost.ru/api/v1',
  apiKey: process.env.LLMOST_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [
    {
      role: 'system',
      content: 'Ты - эксперт по TypeScript.',
    },
    {
      role: 'user',
      content: 'Объясни generic типы в TypeScript',
    },
  ],
  temperature: 0.7,
  max_tokens: 500,
});

console.log(completion.choices[0].message.content);

cURL

curl https://llmost.ru/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Ты - полезный помощник."
      },
      {
        "role": "user",
        "content": "Привет!"
      }
    ],
    "temperature": 0.7
  }'

Go

package main

import (
    "context"
    "fmt"
    "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("ВАШ_API_КЛЮЧ")
    config.BaseURL = "https://llmost.ru/api/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "openai/gpt-4o",
            Messages: []openai.ChatCompletionMessage{
                {
                    Role:    openai.ChatMessageRoleSystem,
                    Content: "Ты - эксперт по Go.",
                },
                {
                    Role:    openai.ChatMessageRoleUser,
                    Content: "Объясни goroutines",
                },
            },
            Temperature: 0.7,
            MaxTokens:   500,
        },
    )

    if err != nil {
        fmt.Printf("Ошибка: %v\n", err)
        return
    }

    fmt.Println(resp.Choices[0].Message.Content)
}

Продвинутые возможности

Мультимодальные запросы

Многие модели поддерживают изображения в качестве входных данных. Используйте массив content с объектами типа image_url:

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Что на этом изображении?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}

Также поддерживаются изображения в base64:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Предварительное заполнение ассистента

Вы можете направить модель, начав ответ за неё:

{
  "messages": [
    {
      "role": "user",
      "content": "Напиши стихотворение о море"
    },
    {
      "role": "assistant",
      "content": "Волны плещут у берега,"
    }
  ]
}

Модель продолжит с того места, где вы остановились.

Вызов инструментов (Function Calling)

Многие модели поддерживают вызов функций для расширения возможностей:

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Какая погода в Москве?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Получить текущую погоду в заданном городе",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "Название города"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

См. Вызов инструментов для подробностей.

Структурированный вывод

Заставьте модель возвращать валидный JSON с помощью параметра response_format:

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Извлеки имя и email из текста: Меня зовут Иван, мой email ivan@example.com"
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}

400 - Неверный запрос (отсутствуют обязательные параметры, неверный формат)
401 - Недействительный или отсутствующий API-ключ
402 - Недостаточно кредитов
403 - Модель недоступна или доступ запрещён
429 - Превышен лимит запросов
500 - Ошибка сервера
502 - Ошибка провайдера модели
503 - Сервис временно недоступен

Пример ответа с ошибкой

{
  "error": {
    "code": 400,
    "message": "Invalid request: 'messages' is required",
    "metadata": {
      "provider": "openai"
    }
  }
}

Обработка ошибок в коде

try {
  const response = await fetch('https://llmost.ru/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'openai/gpt-4o',
      messages: [{ role: 'user', content: 'Привет' }],
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('Ошибка API:', error);

    // Обработка конкретных ошибок
    if (error.error.code === 402) {
      console.log('Недостаточно кредитов, пополните баланс');
    } else if (error.error.code === 429) {
      console.log('Превышен лимит, повторите позже');
    }

    return;
  }

  const data = await response.json();
  console.log(data.choices[0].message.content);
} catch (err) {
  console.error('Ошибка сети:', err);
}

См. Ошибки для полного списка кодов ошибок.

Лучшие практики

1. Используйте системные сообщения

Системные сообщения задают контекст и поведение модели:

{
  "messages": [
    {
      "role": "system",
      "content": "Ты - профессиональный переводчик с английского на русский. Переводи точно и естественно."
    },
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ]
}

2. Управляйте длиной контекста

Следите за количеством токенов, чтобы избежать превышения лимита контекста:

// Оставляйте запас для ответа
const maxResponseTokens = 500;
const maxContextTokens = modelContextLength - maxResponseTokens;

3. Обрабатывайте повторные попытки

Реализуйте экспоненциальную задержку для временных ошибок:

async function completionWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers,
        body: JSON.stringify(payload),
      });

      if (response.ok) {
        return await response.json();
      }

      // Повторить только для временных ошибок
      if (response.status === 429 || response.status >= 500) {
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
        continue;
      }

      throw new Error(`HTTP ${response.status}`);
    } catch (err) {
      if (i === maxRetries - 1) throw err;
    }
  }
}

4. Используйте потоковую передачу для длинных ответов

Улучшите UX с помощью потоковой передачи:

{
  "stream": true,
  "max_tokens": 2000
}

См. Потоковая передача для деталей.

Следующие шаги

Изучите Потоковую передачу для работы в реальном времени
Посмотрите все Параметры для тонкой настройки
Ознакомьтесь с Аутентификацией для безопасной работы
Проверьте доступные Модели для выбора подходящей

POST /chat/completions

На этой странице