Обзор

// Определения подтипов приведены ниже
type Request = {
  // Требуется либо "messages", либо "prompt"
  messages?: Message[];
  prompt?: string;

  // Если "model" не указан, используется модель пользователя по умолчанию
  model?: string; // См. раздел "Поддерживаемые модели"

  // Позволяет заставить модель создавать определенный формат вывода.
  // Поддерживаемые типы: 'text' (обычный текст), 'json_object' (JSON объект), 'json_schema' (JSON с валидацией схемы)
  // См. страницу моделей и примечание на этой странице документации о том, какие модели это поддерживают.
  response_format?:
    | { type: 'text' }
    | { type: 'json_object' }
    | { type: 'json_schema'; json_schema?: Record<string, any> };

  stop?: string | string[];
  stream?: boolean; // Включить потоковую передачу

  // См. Параметры LLM (llmost.ru/docs/api-reference/parameters)
  max_tokens?: number; // Диапазон: [1, context_length)
  temperature?: number; // Диапазон: [0, 2]

  // Вызов инструментов
  // Будет передан как есть для провайдеров, реализующих интерфейс OpenAI.
  // Для провайдеров с пользовательскими интерфейсами мы преобразуем и сопоставляем свойства.
  // В противном случае мы преобразуем инструменты в шаблон YAML. Модель отвечает сообщением ассистента.
  // См. модели, поддерживающие вызов инструментов: llmost.ru/models
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Расширенные необязательные параметры
  seed?: number; // Только целые числа
  top_p?: number; // Диапазон: (0, 1]
  top_k?: number; // Диапазон: [1, Infinity) Недоступно для моделей OpenAI
  frequency_penalty?: number; // Диапазон: [-2, 2]
  presence_penalty?: number; // Диапазон: [-2, 2]
  repetition_penalty?: number; // Диапазон: (0, 2]
  logit_bias?: { [key: number]: number };
  top_logprobs: number; // Только целые числа
  min_p?: number; // Диапазон: [0, 1]
  top_a?: number; // Диапазон: [0, 1]

  // Уменьшите задержку, предоставив модели прогнозируемый вывод
  // https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
  prediction?: { type: 'content'; content: string };
};

// Подтипы:

type TextContent = {
  type: 'text';
  text: string;
};

type ImageContentPart = {
  type: 'image_url';
  image_url: {
    url: string; // URL или данные изображения в кодировке base64
    detail?: string; // Необязательно, по умолчанию "auto"
  };
};

type ContentPart = TextContent | ImageContentPart;

type Message =
  | {
      role: 'user' | 'assistant' | 'system';
      // ContentParts только для роли "user":
      content: string | ContentPart[];
      // Если включено "name", оно будет добавлено так
      // для моделей, отличных от OpenAI: `{name}: {content}`
      name?: string;
    }
  | {
      role: 'tool';
      content: string;
      tool_call_id: string;
      name?: string;
    };

type FunctionDescription = {
  description?: string;
  name: string;
  parameters: object; // Объект JSON Schema
};

type Tool = {
  type: 'function';
  function: FunctionDescription;
};

type ToolChoice =
  | 'none'
  | 'auto'
  | {
      type: 'function';
      function: {
        name: string;
      };
    };

// Пример 1: Обычный текстовый ответ (по умолчанию)
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: 'В чём смысл жизни?',
      },
    ],
  }),
});

// Пример 2: JSON объект
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: 'Верни информацию о пользователе в формате JSON',
      },
    ],
    response_format: { type: 'json_object' },
  }),
});

// Пример 3: JSON с валидацией схемы
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: 'Верни информацию о пользователе',
      },
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          age: { type: 'number' },
        },
        required: ['name'],
      },
    },
  }),
});

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: 'В чём смысл жизни?' },
      { role: 'assistant', content: "Я не уверен, но я предполагаю, что" },
    ],
  }),
});

// Определения подтипов приведены ниже
type Response = {
  id: string;
  // В зависимости от того, установили ли вы "stream" в "true" и
  // передали ли вы "messages" или "prompt", вы
  // получите разную форму вывода
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice)[];
  created: number; // Unix timestamp
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';

  system_fingerprint?: string; // Присутствует только если провайдер это поддерживает

  // Данные использования всегда возвращаются для непотоковой передачи.
  // При потоковой передаче вы получите один объект использования в
  // конце, сопровождаемый пустым массивом choices.
  usage?: ResponseUsage;
};

// Если провайдер возвращает использование, мы передаем его
// как есть. В противном случае мы считаем, используя токенизатор GPT-4.

type ResponseUsage = {
  /** Включая изображения и инструменты, если есть */
  prompt_tokens: number;
  /** Сгенерированные токены */
  completion_tokens: number;
  /** Сумма двух вышеуказанных полей */
  total_tokens: number;
};

// Подтипы:
type NonChatChoice = {
  finish_reason: string | null;
  text: string;
  error?: ErrorResponse;
};

type NonStreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  message: {
    content: string | null;
    role: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type StreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  delta: {
    content: string | null;
    role?: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type ErrorResponse = {
  code: number; // См. раздел "Обработка ошибок"
  message: string;
  metadata?: Record<string, unknown>; // Содержит дополнительную информацию об ошибке, такую как сведения о провайдере, исходное сообщение об ошибке и т.д.
};

type ToolCall = {
  id: string;
  type: 'function';
  function: FunctionCall;
};

{
  "id": "xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // Нормализованная finish_reason
      "native_finish_reason": "stop", // Исходная finish_reason от провайдера
      "message": {
        // будет "delta" при потоковой передаче
        "role": "assistant",
        "content": "Привет!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4,
    "total_tokens": 4
  },
  "model": "openai/gpt-5"
}