Справочник API

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

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

  // Позволяет принудительно задать формат вывода модели.
  // См. раздел "Structured Outputs" ниже и страницу моделей, чтобы узнать, какие модели это поддерживают.
  response_format?: ResponseFormat;

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

  // Плагины для расширения возможностей модели (парсинг PDF, исправление ответов)
  // См. раздел "Plugins": api.vega.chat/docs/guides/features/plugins
  plugins?: Plugin[];

  // См. LLM Parameters (api.vega.chat/docs/api/reference/parameters)
  max_tokens?: number; // Диапазон: [1, context_length)
  temperature?: number; // Диапазон: [0, 2]

  // Вызов инструментов
  // Будет передан без изменений провайдерам, реализующим интерфейс OpenAI.
  // Для провайдеров с кастомными интерфейсами мы трансформируем и сопоставляем свойства.
  // Иначе мы преобразуем инструменты в шаблон YAML. Модель отвечает сообщением‑ассистентом.
  // См. модели, поддерживающие вызов инструментов: /aimodels?supported_parameters=tools
  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 };

  // Параметры, специфичные только для VEGA
  // См. раздел "Model Routing": api.vega.chat/docs/guides/features/model-routing
  models?: string[];
  route?: 'fallback';
  // См. раздел "Provider Routing": api.vega.chat/docs/guides/routing/provider-selection
  provider?: ProviderPreferences;
  user?: string; // Стабильный идентификатор ваших конечных пользователей. Помогает обнаруживать и предотвращать злоупотребления.

  // Параметры отладки (только при потоковой передаче)
  debug?: {
    echo_upstream_body?: boolean; // Если true, возвращает трансформированное тело запроса, отправленное провайдеру
  };
};

// Подтипы:

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 object
};

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

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

// Формат ответа для структурированных выводов
type ResponseFormat =
  | { type: 'json_object' }
  | {
      type: 'json_schema';
      json_schema: {
        name: string;
        strict?: boolean;
        schema: object; // JSON Schema object
      };
    };

// Конфигурация плагинов
type Plugin = {
  id: string; // 'web', 'file-parser', 'response-healing', 'context-compression'
  enabled?: boolean;
  // Дополнительные опции, специфичные для плагина
  [key: string]: unknown;
};

{
  "plugins": [
    { "id": "web" },
    { "id": "response-healing" }
  ]
}

fetch('https://api.vega.chat/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <VEGA_API_KEY>',
    'HTTP-Referer': '<YOUR_SITE_URL>', // Необязательно. URL сайта для ранжирования на VEGA.
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // Необязательно. Название сайта для ранжирования на VEGA.
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      {
        role: 'user',
        content: 'What is the meaning of life?',
      },
    ],
  }),
});

fetch('https://api.vega.chat/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <VEGA_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      { role: 'user', content: 'What is the meaning of life?' },
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
    ],
  }),
});

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

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

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

// **VEGA** всегда возвращает подробную информацию об использовании.
// Подсчёт токенов производится токенизатором модели.

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

  /** Детализация токенов prompt (необязательно) */
  prompt_tokens_details?: {
    cached_tokens: number;        // Токены, кэшированные эндпоинтом
    cache_write_tokens?: number;  // Токены, записанные в кэш (модели с явным кэшированием)
    audio_tokens?: number;        // Токены, использованные для входного аудио
    video_tokens?: number;        // Токены, использованные для входного видео
  };

  /** Детализация токенов completion (необязательно) */
  completion_tokens_details?: {
    reasoning_tokens?: number;    // Токены, сгенерированные для рассуждений
    audio_tokens?: number;        // Токены, сгенерированные для аудио‑вывода
    image_tokens?: number;        // Токены, сгенерированные для вывода изображений
  };

  /** Стоимость в кредитах (необязательно) */
  cost?: number;
  /** Был ли запрос выполнен с использованием Bring Your Own Key */
  is_byok?: boolean;
  /** Подробный расчёт стоимости (необязательно) */
  cost_details?: {
    upstream_inference_cost?: number;             // Показано только для BYOK‑запросов
    upstream_inference_prompt_cost: number;
    upstream_inference_completions_cost: number;
  };

  /** Использование серверных инструментов (необязательно) */
  server_tool_use?: {
    web_search_requests?: 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; // См. раздел "Error Handling"
  message: string;
  metadata?: Record<string, unknown>; // Содержит дополнительную информацию об ошибке, например детали провайдера, сырое сообщение об ошибке и т.д.
};

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

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // Нормализованный finish_reason
      "native_finish_reason": "stop", // Исходный finish_reason от провайдера
      "message": {
        // будет "delta", если поток
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    },
    "cost": 0.00014
  },
  "model": "openai/gpt-4o" // Может быть также "anthropic/claude-sonnet-4.6" и др., в зависимости от фактически использованной модели
}

const generation = await fetch(
  'https://api.vega.chat/api/v1/generation?id=$GENERATION_ID',
  { headers },
);

const stats = await generation.json();