К содержимому

Подключение к API Relay

Relay поддерживает совместимые форматы API: OpenAI, OpenAI Responses и Anthropic. Модели Gemini работают через OpenAI-совместимый формат при наличии в каталоге. Нативный протокол Gemini не поддерживается.

  • Base URL: https://relay-llm.ru
  • Аутентификация: API Key (sk-rly-...)
  • Протоколы: нативный формат Anthropic (/v1/messages), OpenAI-совместимый формат (/v1/chat/completions), OpenAI Responses API (/v1/responses при поддержке моделью), модели Gemini через (/v1/chat/completions) и генерация изображений (/v1/images/generations)

Замените YOUR_API_KEY на свой ключ. Держите ключ в секрете и никогда не коммитьте его в репозиторий.


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

Выберите совместимый формат в зависимости от модели:

Разные форматы используют разные заголовки аутентификации. Выберите заголовок по протоколу:

ПротоколЗаголовок
Anthropicx-api-key: YOUR_API_KEY + anthropic-version: 2023-06-01
OpenAIAuthorization: Bearer YOUR_API_KEY
GeminiAuthorization: Bearer YOUR_API_KEY

2. Доступные модели

Полный актуальный список моделей можно получить через GET /v1/models:

bash
curl https://relay-llm.ru/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Доступные сейчас модели (примеры):

ПровайдерID модели
Anthropicclaude-fable-5, claude-fable-5-1, claude-fable-5-2, claude-haiku-5-5, claude-opus-5-5, claude-sonnet-5-5, , ,
OpenAIgpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-6.1-sol, gpt-6.1-terra, gpt-6-astra, gpt-6-luna, gpt-6-sol
Googlegemini-3.1-pro, gemini-3.7-flash, gemini-3.8-flash, gemini-4-argon, nano-banana, nano-banana-2, nano-banana-pro
DeepSeekdeepseek-v4.1-flash, deepseek-v4.1-flash-1017, deepseek-v4.1-flash-1017-free, deepseek-v4.1-flash-1017-uncensored, deepseek-v4-flash, deepseek-v4-pro (DeepSeek V4 Pro)
Z-AIglm-5.2, glm-5.3, glm-5.3-flash,
xAIgrok-4.5

3. Нативный формат Anthropic

Эндпоинт: POST /v1/messages

3.1 Базовый запрос

bash
curl https://relay-llm.ru/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Introduce yourself in one sentence"}
    ]
  }'

Пример ответа:

json
{
  "id": "msg_01KxDE...",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-5-5",
  "content": [{"type": "text", "text": "I am Claude..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 159, "output_tokens": 34}
}

3.2 Потоковый ответ (streaming) через SSE

Добавьте "stream": true. Ответ придёт как text/event-stream:

bash
curl https://relay-llm.ru/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short poem"}]
  }'

Последовательность событий: message_start -> content_block_start -> несколько content_block_delta -> content_block_stop -> message_delta -> message_stop.

3.3 Python SDK anthropic

python
from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://relay-llm.ru",
)

resp = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content[0].text)

4. OpenAI-совместимый формат

Эндпоинты: POST /v1/chat/completions (Chat Completions) и POST /v1/responses (Responses API, только модели GPT)

4.1 Базовый запрос Chat Completions

bash
curl https://relay-llm.ru/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Ответ соответствует стандартной структуре OpenAI chat.completion:

json
{
  "object": "chat.completion",
  "model": "gpt-5.6-luna",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 214, "completion_tokens": 3, "total_tokens": 217}
}

4.2 Python SDK openai

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://relay-llm.ru/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-luna",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

4.3 Потоковый ответ

Добавьте "stream": true. Relay возвращает стандартные SSE-чанки OpenAI в формате data: {...} и завершает поток data: [DONE].

4.4 Базовый запрос Responses API

Если приложение уже использует OpenAI Responses API, обращайтесь напрямую к /v1/responses:

bash
curl https://relay-llm.ru/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "input": "Introduce Relay in one sentence"
  }'

/v1/responses поддерживает только модели GPT. Запросы к Claude / Gemini возвращают 400. Для Claude используйте /v1/messages, для Gemini используйте OpenAI-совместимый формат.

4.5 Python SDK openai Responses

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://relay-llm.ru/v1",
)

resp = client.responses.create(
    model="gpt-5.6-luna",
    input="Introduce Relay in one sentence",
)
print(resp.output_text)

4.6 Потоковый ответ Responses API

Добавьте "stream": true, чтобы получать стандартные потоковые события OpenAI Responses API.

4.7 Обычный тариф Relay

Приоритетного тарифа у Relay нет. Используйте стандартные параметры запроса:

json
"stream": false

Пример на Python:

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://relay-llm.ru/v1",
)

resp = client.responses.create(
    model="gpt-5.6-luna",
    input="Analyze this requirement for me",
    instructions="Reply with OK",
)
print(resp.output_text)

Пример на JavaScript:

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://relay-llm.ru/v1",
});

const resp = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "Analyze this requirement for me",
  instructions: "Reply with OK",
});
console.log(resp.output_text);

Потоковый режим задаётся параметром:

json
"stream": true

stream включает потоковый ответ. Параметр service_tier не включает отдельный тариф Relay. Для модели gpt-5.6-luna цена определяется каталогом. Проверяйте результат запроса и поле usage в ответе; значение service_tier не обещает ускорения.


5. Gemini через OpenAI-совместимый формат

Эндпоинт: POST /v1/chat/completions

5.1 Базовый запрос

bash
curl https://relay-llm.ru/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "Reply with OK"}
    ]
  }'

Пример ответа:

json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "OK"
      }
    }
  ]
}

5.2 Потоковый ответ через SSE

Используйте stream: true и добавьте alt=sse:

bash
curl "https://relay-llm.ru/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Reply with OK"}
    ]
  }'

5.3 Переменные окружения

Если ваш инструмент или SDK поддерживает пользовательский Base URL Gemini, настройте так:

bash
export OPENAI_BASE_URL="https://relay-llm.ru/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
export RELAY_API_KEY="$OPENAI_API_KEY"

Разные SDK Gemini могут называть поле для пользовательского эндпоинта по-разному: base_url, baseURL, apiEndpoint или переменные окружения. Главное правило: направьте Base URL на https://relay-llm.ru и используйте API Key Relay.


6. Генерация изображений (GPT Image 2)

Модель изображений gpt-image-2 использует отдельные эндпоинты /v1/images и аутентификацию Authorization: Bearer.

6.1 Генерация изображений

Эндпоинт: POST /v1/images/generations

bash
curl https://relay-llm.ru/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "An orange cat typing on a keyboard, illustration style"
  }'

Пример ответа. data[0].b64_json , изображение в Base64:

json
{
  "created": 1752345600,
  "data": [
    {"b64_json": "iVBORw0KGgo..."}
  ]
}

Установите таймаут 300 секунд. Модели генерации изображений отвечают дольше, и с коротким таймаутом запрос может не завершиться.

6.2 Редактирование изображений

Эндпоинт: POST /v1/images/edits

Загрузите исходное изображение как multipart/form-data и передайте инструкцию:

bash
curl https://relay-llm.ru/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="gpt-image-2" \
  -F image="@photo.png" \
  -F prompt="Replace the background with a starry sky"

Эндпоинт совместим с OpenAI Images API.


7. Подключение агентных инструментов

Claude Code использует протокол Anthropic, Codex , протокол OpenAI, Gemini CLI , протокол Gemini.

Достаточно направить переменные окружения Base URL и API Key на Relay. Сами инструменты менять не нужно.

Claude Code (протокол Anthropic):

bash
export ANTHROPIC_BASE_URL="https://relay-llm.ru"
export ANTHROPIC_API_KEY="YOUR_API_KEY"

Инструменты с протоколом OpenAI (Chat Completions / Responses API):

bash
export OPENAI_BASE_URL="https://relay-llm.ru/v1"
export OPENAI_API_KEY="YOUR_API_KEY"

Gemini CLI:

bash
export OPENAI_BASE_URL="https://relay-llm.ru/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
export RELAY_API_KEY="$OPENAI_API_KEY"

8. FAQ

Получаете 401 / ошибку аутентификации?

Сначала проверьте соответствие протокола и заголовка: Anthropic использует x-api-key; OpenAI / Gemini , Authorization: Bearer; нативные эндпоинты Gemini также принимают x-goog-api-key. Затем убедитесь, что ключ полный, начинается с sk-rly-, без лишних пробелов и не удалён в консоли. Проверьте и формат base_url: SDK OpenAI требуют /v1; SDK Anthropic , нет.

Вызов Claude через формат OpenAI даёт ошибки, стоит дороже или работает хуже?

Для моделей Claude по возможности используйте нативный протокол Anthropic (/v1/messages). Claude Code и другие агентные инструменты нужно настраивать на протокол Anthropic. Вызов Claude через OpenAI-совместимый формат может терять кэш промптов, режим рассуждений и другие возможности, что повышает стоимость и снижает качество. Он подходит только для простых чат-сценариев. /v1/responses не поддерживает Claude / Gemini и возвращает 400.

У запросов к Claude и чтение, и запись кэша равны 0?

Кэширование Claude нужно включать явно на стороне вызывающего. В нативном протоколе Anthropic (/v1/messages) добавьте "cache_control": {"type": "ephemeral"} в конец контента, который нужно переиспользовать, , обычно в последний блок system, последний инструмент и последнее сообщение. Без этого ничего не кэшируется, и чтение, и запись кэша равны 0. Вызов Claude через OpenAI-совместимый формат не включает кэширование автоматически, а контент короче минимальной длины, которую модель может кэшировать, тоже не кэшируется.

bash
curl https://relay-llm.ru/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 1024,
    "system": [
      {"type": "text", "text": "Длинный неизменный системный промпт", "cache_control": {"type": "ephemeral"}}
    ],
    "messages": [
      {"role": "user", "content": [
        {"type": "text", "text": "Представься одним предложением", "cache_control": {"type": "ephemeral"}}
      ]}
    ]
  }'

После включения в возвращаемом usage поле cache_creation_input_tokens , это запись кэша, а cache_read_input_tokens , чтение кэша. Кэш сопоставляется по префиксу: всё, что стоит до метки cache_control (system, tools, предыдущие сообщения), должно совпадать от запроса к запросу. Любое изменение делает недействительным кэш после него.

Модель недоступна?

Сначала получите актуальный список через GET /v1/models. Проверьте написание ID модели: строчные буквы, не путайте - и .. Убедитесь, что эндпоинт соответствует модели.

Таймаут или медленный первый токен?

Крупные модели вроде Opus / Fable во время рассуждений могут отдавать первый токен через несколько секунд или десятки секунд. Это не значит, что запрос упал. В продакшене включайте "stream": true для лучшей воспринимаемой задержки и увеличивайте таймаут чтения у клиента. Сервер поддерживает ответы длительностью до 600 секунд.

Получаете 402 insufficient_balance?

API возвращает 402, когда доступного баланса не хватает на резерв запроса. Пополните баланс способом, который показан в форме. Подробнее: баланс и платежи. Правила списания , в разделе Оплата.

Безопасность ключа:

Храните ключи в переменных окружения или менеджере секретов. Не записывайте ключи прямо в код, не добавляйте их в Git и не встраивайте во фронтенд / публичный клиент. Если подозреваете утечку, немедленно удалите ключ в консоли и создайте новый.

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key