Для получения чистого Markdown любой страницы добавьте .md к URL страницы.
Для полного индекса документации см. https://api.vega.chat/docs/llms.txt.
Для полного содержания документации см. https://api.vega.chat/docs/llms-full.txt.
Для интеграции AI‑клиентов (Claude Code, Cursor и др.) подключитесь к MCP‑серверу по адресу https://api.vega.chat/docs/_mcp/server.

Метаданные роутера экспериментальны. Формат ответа openrouter_metadata нестабилен: поля и типы этапов конвейера могут добавляться, переименовываться, удаляться или менять семантику в любой момент, без цикла устаревания. Пока не привязывайте производственные инструменты к конкретным именам полей или значениям.

Роутер VEGA обрабатывает каждый запрос через многоступенчатый конвейер: он выбирает провайдера, может сжимать контекст, может запускать ограничительные механизмы, может вызывать серверные инструменты и может повторять запросы к резервным провайдерам. По умолчанию ничего из этого не видно в ответе.

Метаданные роутера — это опциональное включение на каждый запрос, которое добавляет поле openrouter_metadata к успешным ответам, фиксируя точно, что сделал роутер. Это предназначено для отладки решений маршрутизации, атрибуции задержек или стоимости и аудита поведения конвейера.

Включение метаданных роутера

Включите, отправив заголовок запроса X-OpenRouter-Experimental-Metadata со значением enabled:

curl https://api.vega.chat/api/v1/chat/completions \
  -H "Authorization: Bearer {{API_KEY_REF}}" \
  -H "Content-Type: application/json" \
  -H "X-OpenRouter-Experimental-Metadata: enabled" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

const response = await fetch('https://api.vega.chat/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer {{API_KEY_REF}}`,
    'Content-Type': 'application/json',
    'X-OpenRouter-Experimental-Metadata': 'enabled',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});

import requests

response = requests.post(
    'https://api.vega.chat/api/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {{API_KEY_REF}}',
        'Content-Type': 'application/json',
        'X-OpenRouter-Experimental-Metadata': 'enabled',
    },
    json={
        'model': 'openai/gpt-4o-mini',
        'messages': [{'role': 'user', 'content': 'Hello'}],
    },
)

Принимаемые значения

Заголовок принимает следующие значения, без учёта регистра:

Любое другое значение (включая опечатки, пустые строки и неизвестные уровни) приводит к disabled. Поведение по умолчанию — когда заголовок отсутствует — disabled.

Поддерживаемые конечные точки

Метаданные роутера встроены во все публичные маршруты завершения:

• /api/v1/chat/completions (OpenAI Chat Completions)
• /api/v1/messages (Anthropic Messages)
• /api/v1/responses (OpenAI Responses)
• /api/v1/completions (legacy text completions)

Как стриминговые, так и нестриминговые запросы передают поле, когда включено. Для стриминговых ответов openrouter_metadata доставляется в последнем чанке перед data: [DONE] (Chat Completions / Responses) или как часть завершающего события message_stop (Anthropic Messages).

Формат ответа

При включённом режиме успешные ответы включают объект openrouter_metadata рядом с остальными данными ответа:

{
  "id": "gen-...",
  "model": "openai/gpt-4o-mini",
  "choices": [...],
  "usage": {...},
  "openrouter_metadata": {
    "requested": "openai/gpt-4o-mini",
    "strategy": "direct",
    "region": "iad",
    "summary": "available=1, selected=OpenAI",
    "attempt": 1,
    "is_byok": false,
    "endpoints": {
      "total": 1,
      "available": [
        {
          "provider": "OpenAI",
          "model": "openai/gpt-4o-mini",
          "selected": true
        }
      ]
    },
    "attempts": [
      { "provider": "OpenAI", "model": "openai/gpt-4o-mini", "status": 200 }
    ],
    "pipeline": [
      {
        "type": "context_compression",
        "name": "context-compression",
        "data": {
          "engine": "middle-out",
          "input_type": "messages",
          "original_count": 42,
          "compressed_count": 30
        }
      }
    ]
  }
}

Справочник полей

Полная схема задокументирована в OpenRouterMetadata в спецификации OpenAPI, включая определения типов SDK для TypeScript и других сгенерированных клиентов.

Этапы конвейера

Массив pipeline фиксирует каждый плагин, который существенно повлиял на запрос. Плагин записывает этап только тогда, когда действительно выполнился; плагин‑нулевой (например, сжатие контекста, которое обнаружило, что вход уже укладывается в бюджет) опускается. Текущие типы этапов включают:

Несколько плагинов могут иметь один и тот же type. Чтобы найти конкретный ограничительный механизм (например, фильтр контента), пройдите массив и сопоставьте одновременно type === 'guardrail' и name === 'content-filter'. Полный набор плагинов уровня guardrail выдаёт type: 'guardrail', так что их можно отфильтровать вместе (pipeline.filter(s => s.type === 'guardrail')) без перечисления отдельных плагинов.

Список растёт со временем. Неизвестные типы этапов рассматривайте как непрозрачные — data по замыслу является свободной записью, позволяя плагинам прикреплять свою телеметрию без изменения схемы.

Попадания в кэш

Попадания в кэш никогда не включают openrouter_metadata. Как стриминговые, так и нестриминговые воспроизведения кэша удаляют это поле, чтобы клиенты не могли привязывать поведение к устаревшим данным маршрутизации. Это сделано намеренно: метаданные, которые вы видите при промахе кэша, могут не отражать маршрутизацию, породившую кэшированный полезный груз.

Ошибочные ответы

Опциональные ошибочные ответы выводят openrouter_metadata на верхнем уровне оболочки ошибки, повторяя расположение в успешном пути (сосед error, а не вложенный в него). Это относится ко всем четырём маршрутам — Chat Completions, Messages, Responses и legacy Completions — и к стриминговым, и к нестриминговым запросам. Те же правила включения применяются: отправьте X-OpenRouter-Experimental-Metadata: enabled, и снимок будет включён при ошибке; если заголовок опущен, он не будет.

Нет доступных провайдеров (404)

{
  "error": {
    "code": 404,
    "message": "No allowed providers are available for the selected model"
  },
  "openrouter_metadata": {
    "requested": "openai/gpt-4o-mini",
    "strategy": "direct",
    "attempt": 0,
    "endpoints": {
      "total": 1,
      "available": [
        {
          "provider": "OpenAI",
          "model": "openai/gpt-4o-mini",
          "selected": false
        }
      ]
    }
  }
}

Ограничительный механизм заблокировал (403)

Когда запрос блокируется до обращения к провайдеру — например, фильтром контента или детектором внедрения подсказки, настроенным через guardrails — ответ включает полный объект openrouter_metadata с контекстом маршрутизации и массив pipeline, показывающий каждый этап guardrail, включая тот, который заблокировал:

{
  "error": {
    "code": 403,
    "message": "Request blocked: prompt injection patterns detected",
    "metadata": {
      "patterns": ["ignore all previous instructions"]
    }
  },
  "openrouter_metadata": {
    "requested": "openai/gpt-4o",
    "strategy": "direct",
    "region": "iad",
    "summary": "available=1",
    "attempt": 1,
    "is_byok": false,
    "endpoints": {
      "total": 1,
      "available": [
        { "provider": "OpenAI", "model": "openai/gpt-4o", "selected": false }
      ]
    },
    "pipeline": [
      {
        "type": "guardrail",
        "name": "regex_pi_detection",
        "guardrail_id": "grd_abc123",
        "guardrail_scope": "api-key",
        "summary": "Blocked: prompt injection detected (1 pattern matched)",
        "data": {
          "action": "blocked",
          "detected": true,
          "engines": ["regex"],
          "patterns": ["ignore all previous instructions"]
        }
      }
    ]
  }
}

Поскольку блокировки guardrail происходят до завершения вызова провайдера, ни один эндпоинт не помечен как selected, а массив attempts отсутствует.

Несколько важных моментов:

• attempt отражает, насколько далеко дошёл роутер. Значение 0 означает, что запрос никогда не достиг провайдера — обычно потому, что каждый кандидат был отфильтрован до отправки (например, provider.only исключил последний эндпоинт, или фильтр allowed‑providers / max‑price отклонил всё). Значения ≥ 1 означают, что все попытки провайдеров завершились неудачей и резервные варианты исчерпаны.
• На ошибке ни один эндпоинт не помечен selected. Ни один из флагов endpoints.available[].selected не равен true, потому что ни один эндпоинт фактически не отдал статус 200.
• Маскирование внутренних ошибок всё ещё действует. Ответы со статусом 500 очищаются до общего сообщения, и openrouter_metadata опускается в этих оболочках по дизайну — мы не раскрываем детали внутренней маршрутизации при ошибках, причина которых уже скрыта. Другие коды 5xx (502, 503, 504, 529) всё ещё включают метаданные, если клиент включил их.
• Некоторые режимы отказов не будут включать метаданные. Ошибки аутентификации / ограничения по скорости и другие ошибки, возникающие до того, как роутер получил пригодное состояние маршрутизации (например, отклонения валидации на границе API), не будут содержать поле. Если вам нужен постмортем контекст маршрутизации для запроса, который прошёл границу API, но не дошёл до материализации состояния роутера, получите запись генерации через GET /api/v1/generation, используя заголовок ответа X-Generation-Id.

Стабильность

Метаданные роутера экспериментальны. Формат ответа openrouter_metadata нестабилен — поля и типы этапов конвейера могут добавляться, переименовываться, удаляться или менять семантику в любой момент, без цикла устаревания. Рассматривайте полезную нагрузку как отладочную телеметрию «best‑effort», а не как стабильный контракт.

Заголовок X-OpenRouter-Experimental-Metadata — поддерживаемый способ включения функции, но имя заголовка и принимаемые значения также могут измениться, пока функция остаётся экспериментальной.

Если вы используете это поле в коде, декодируйте его допускающе (рассматривайте неизвестные поля и типы этапов как непрозрачные) и будьте готовы к обновлениям при каждом релизе.