Подключение к 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. Аутентификация
Выберите совместимый формат в зависимости от модели:
Разные форматы используют разные заголовки аутентификации. Выберите заголовок по протоколу:
| Протокол | Заголовок |
|---|---|
| Anthropic | x-api-key: YOUR_API_KEY + anthropic-version: 2023-06-01 |
| OpenAI | Authorization: Bearer YOUR_API_KEY |
| Gemini | Authorization: Bearer YOUR_API_KEY |
2. Доступные модели
Полный актуальный список моделей можно получить через GET /v1/models:
curl https://relay-llm.ru/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
Доступные сейчас модели (примеры):
| Провайдер | ID модели |
|---|---|
| Anthropic | claude-fable-5, claude-fable-5-1, claude-fable-5-2, claude-haiku-5-5, claude-opus-5-5, claude-sonnet-5-5, , , |
| OpenAI | gpt-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 |
gemini-3.1-pro, gemini-3.7-flash, gemini-3.8-flash, gemini-4-argon, nano-banana, nano-banana-2, nano-banana-pro | |
| DeepSeek | deepseek-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-AI | glm-5.2, glm-5.3, glm-5.3-flash, |
| xAI | grok-4.5 |
3. Нативный формат Anthropic
Эндпоинт: POST /v1/messages
3.1 Базовый запрос
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"}
]
}'
Пример ответа:
{
"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:
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
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
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:
{
"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
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:
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
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 нет. Используйте стандартные параметры запроса:
"stream": false
Пример на 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:
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);
Потоковый режим задаётся параметром:
"stream": true
stream включает потоковый ответ. Параметр service_tier не включает отдельный тариф Relay. Для модели gpt-5.6-luna цена определяется каталогом. Проверяйте результат запроса и поле usage в ответе; значение service_tier не обещает ускорения.
5. Gemini через OpenAI-совместимый формат
Эндпоинт: POST /v1/chat/completions
5.1 Базовый запрос
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"}
]
}'
Пример ответа:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "OK"
}
}
]
}
5.2 Потоковый ответ через SSE
Используйте stream: true и добавьте alt=sse:
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, настройте так:
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
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:
{
"created": 1752345600,
"data": [
{"b64_json": "iVBORw0KGgo..."}
]
}
Установите таймаут 300 секунд. Модели генерации изображений отвечают дольше, и с коротким таймаутом запрос может не завершиться.
6.2 Редактирование изображений
Эндпоинт: POST /v1/images/edits
Загрузите исходное изображение как multipart/form-data и передайте инструкцию:
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):
export ANTHROPIC_BASE_URL="https://relay-llm.ru"
export ANTHROPIC_API_KEY="YOUR_API_KEY"
Инструменты с протоколом OpenAI (Chat Completions / Responses API):
export OPENAI_BASE_URL="https://relay-llm.ru/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
Gemini CLI:
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-совместимый формат не включает кэширование автоматически, а контент короче минимальной длины, которую модель может кэшировать, тоже не кэшируется.
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 и не встраивайте во фронтенд / публичный клиент. Если подозреваете утечку, немедленно удалите ключ в консоли и создайте новый.