Обзор API

Адрес, аутентификация, маршруты и ошибки Veda AI Gateway. Общие правила для всех форматов.

Veda AI Gateway поддерживает несколько форматов API. Все они используют один адрес, один ключ и один каталог моделей. Тело запроса передаётся выбранной модели без изменений, поэтому стандартные параметры каждого формата работают так, как их поддерживает модель.

Адрес

$VEDA_BASE_URL/v1

Здесь VEDA_BASE_URL означает адрес вашего Veda AI Gateway без пути, например http://localhost:3002 для локальной установки. Префикс /api/v1 принимается как синоним /v1.

Клиент	Базовый адрес
OpenAI SDK, AI SDK, клиенты Open Responses, HTTP	`$VEDA_BASE_URL/v1`
Anthropic SDK, Claude Code	`$VEDA_BASE_URL`

Anthropic SDK сам добавляет /v1/messages к базовому адресу, поэтому ему передаётся адрес без /v1.

Аутентификация

Каждый запрос передаёт API-ключ Veda в заголовке Authorization:

Authorization: Bearer $VEDA_API_KEY

Это правило действует для всех маршрутов, в том числе для /v1/messages. Заголовок x-api-key не используется: в Anthropic SDK передавайте ключ в authToken, а не в apiKey.

Маршруты

Метод и путь	Назначение	Формат
`POST /v1/chat/completions`	Генерация ответа по списку сообщений	OpenAI Chat Completions
`POST /v1/responses`	Генерация ответа по элементам ввода	OpenAI Responses, Open Responses
`POST /v1/messages`	Генерация ответа в формате Anthropic	Anthropic Messages
`POST /v1/embeddings`	Векторные представления текста	Поля `model` и `input`
`POST /v1/rerank`	Ранжирование документов по запросу	Поля `model`, `query` и `documents`
`POST /v1/images`	Генерация изображений	Поля `model` и `prompt`
`POST /v1/audio/speech`	Синтез речи из текста	Поля `model` и `input`
`POST /v1/audio/transcriptions`	Распознавание речи	`multipart/form-data` с полями `file` и `model`

Все маршруты принимают JSON. multipart/form-data принимает только /v1/audio/transcriptions. Маршрута списка моделей в API нет: доступные модели и их идентификаторы смотрите в каталоге.

Модели

Модель задаётся полем model с идентификатором вида автор/модель:

anthropic/claude-sonnet-5.5
openai/gpt-6.1-sol
google/gemini-3.8-flash

Любую модель из каталога можно вызвать в любом из текстовых форматов. Возможности (рассуждения, изображения на входе, вызов инструментов, структурированный вывод) зависят от модели. На странице модели в каталоге показаны только те, что она поддерживает.

Потоковая передача

Во всех текстовых форматах поток включается полем "stream": true. Ответ приходит как text/event-stream (Server-Sent Events). Veda передаёт события клиенту по мере поступления, не накапливая ответ. Формат событий соответствует выбранному API и описан на странице формата.

Ошибки

Veda проверяет ключ, лимит расходов и частоту запросов до обращения к модели. Такие ошибки возвращаются в едином формате:

{ "error": { "code": 401, "message": "Invalid API key" } }

На маршруте /v1/messages те же ошибки приходят в формате Anthropic, чтобы Anthropic SDK разобрал их штатно:

{
  "type": "error",
  "error": { "type": "authentication_error", "message": "Invalid API key" },
  "request_id": "cc8fc6b3-8b62-4c6b-8d4d-8402df4bb560"
}

Код	Сообщение	Причина
`400`	`Invalid JSON`, `Request body must be a JSON object`, `model must be a string`	Тело запроса не является JSON-объектом или поле `model` задано неверно
`401`	`Invalid API key`	Ключ не передан, неверен, отключён, удалён или его срок действия истёк
`402`	`API key spending limit reached`	Достигнут лимит расходов ключа за текущий период
`404`	`Not found`	Неизвестный маршрут
`415`	`Multipart body is not supported for this endpoint`	`multipart/form-data` на маршруте, который принимает только JSON
`429`	`Rate limit exceeded`	Превышено ограничение частоты запросов ключа
`502`	`Upstream unavailable`, `Upstream provider unavailable`	Модель временно недоступна. Повторите запрос позже
`503`	`Key store unavailable`, `Key budget unavailable`, `Rate limit unavailable`	Временно недоступна проверка ключа или учёт лимитов. Повторите запрос позже

Ошибки, которые возвращает сама модель (например, неподдерживаемый параметр), передаются клиенту с их исходным кодом и телом. Подробнее о лимитах: Ключи и лимиты.

Заголовки

Заголовок	Назначение
`Authorization`	`Bearer $VEDA_API_KEY`, обязателен
`Content-Type`	`application/json`; для распознавания речи `multipart/form-data`
`anthropic-version`, `anthropic-beta`	Передаются модели без изменений; Anthropic SDK выставляет их сам
`X-Veda-App-Id`, `X-Veda-App-Name`, `X-Veda-App-Url`	Атрибуция приложения, см. Статистика приложений

АдресСкопировать ссылку на раздел

АутентификацияСкопировать ссылку на раздел

МаршрутыСкопировать ссылку на раздел

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

Потоковая передачаСкопировать ссылку на раздел

ОшибкиСкопировать ссылку на раздел

ЗаголовкиСкопировать ссылку на раздел