API

Документация

Подключение OpenAI-совместимого API Scarlex к SDK и редакторам.
👤 …

Быстрый старт

Scarlex — это OpenAI-совместимый прокси к Anthropic Claude. Любой SDK или редактор, поддерживающий OpenAI Chat Completions, можно подключить, указав базовый URL и API-ключ.

ПараметрЗначение
Base URLhttps://api.scarlex.ru/v1
АвторизацияAuthorization: Bearer YOUR_KEY
ФорматOpenAI Chat Completions

Ключ берётся из раздела Ключи. Биллинг — по токенам (prompt_tokens + completion_tokens), списание с лимита ключа.

curl https://api.scarlex.ru/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.7",
    "messages": [{"role":"user","content":"Привет!"}]
  }'

Авторизация

Заголовок Authorization: Bearer YOUR_KEY. Ключ передаётся в каждом запросе. Без ключа или с неверным — 401 Unauthorized.

Один ключ = один лимит токенов. При исчерпании — 402 Payment Required. Пополнение в разделе Ключи или Маркет.

OpenAI Python SDK

Установка: pip install openai

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.scarlex.ru/v1",
)
resp = client.chat.completions.create(
    model="claude-opus-4.7",
    messages=[{"role":"user","content":"Привет!"}],
    max_tokens=1024,
)
print(resp.choices[0].message.content)

OpenAI Node.js SDK

Установка: npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_KEY",
  baseURL: "https://api.scarlex.ru/v1",
});

const r = await client.chat.completions.create({
  model: "claude-opus-4.7",
  messages: [{ role: "user", content: "Привет!" }],
  max_tokens: 1024,
});
console.log(r.choices[0].message.content);

cURL

Non-stream:

curl https://api.scarlex.ru/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.7",
    "messages": [{"role":"user","content":"Объясни рекурсию"}],
    "temperature": 0.7,
    "max_tokens": 512
  }'

Stream (SSE):

curl -N https://api.scarlex.ru/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.7",
    "stream": true,
    "messages": [{"role":"user","content":"Расскажи историю"}]
  }'

Anthropic SDK

Прокси также поддерживает нативный Anthropic Messages API через /v1/messages. Можно использовать официальный SDK anthropic без изменений в коде, только подменив base URL.

Установка: pip install anthropic

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_KEY",
    base_url="https://api.scarlex.ru",
)
msg = client.messages.create(
    model="claude-opus-4.7",
    max_tokens=1024,
    messages=[{"role":"user","content":"Привет!"}],
)
print(msg.content[0].text)

Anthropic Node.js SDK

Установка: npm install @anthropic-ai/sdk

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "YOUR_KEY",
  baseURL: "https://api.scarlex.ru",
});

const msg = await client.messages.create({
  model: "claude-opus-4.7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Привет!" }],
});
console.log(msg.content[0].text);

Claude Code

Официальный CLI от Anthropic. Установи и настрой через переменные окружения:

npm install -g @anthropic-ai/claude-code

export ANTHROPIC_BASE_URL=https://api.scarlex.ru
export ANTHROPIC_API_KEY=YOUR_KEY

claude

Работает напрямую через эндпоинт /v1/messages. Поддерживается streaming, function calling, multi-turn диалоги.

Особенности: server-side tools (text_editor, bash, web_search, computer) отфильтровываются на стороне прокси. Если требуется агентное редактирование файлов — Claude Code работает локально, прокси только генерирует ответы модели.

Cursor

Настройки → Models → секция OpenAI API Key:

  • OpenAI API Key: YOUR_KEY
  • Override OpenAI Base URL: https://api.scarlex.ru/v1
  • Добавить кастомную модель: claude-opus-4.7 (и любые другие — см. Маркет).
  • Сохранить и проверить кнопкой Verify.

Continue.dev

В ~/.continue/config.json добавь модель:

{
  "models": [
    {
      "title": "Scarlex Opus 4.7",
      "provider": "openai",
      "model": "claude-opus-4.7",
      "apiKey": "YOUR_KEY",
      "apiBase": "https://api.scarlex.ru/v1"
    }
  ]
}

OpenCode

В ~/.config/opencode/opencode.json используй провайдер @ai-sdk/openai-compatible:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "Scarlex/claude-opus-4.7",
  "provider": {
    "Scarlex": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Scarlex",
      "options": {
        "baseURL": "https://api.scarlex.ru",
        "apiKey": "YOUR_KEY"
      },
      "models": {
        "claude-opus-4.7": {
          "name": "Claude Opus 4.7",
          "limit": { "context": 200000, "output": 64000 },
          "variants": { "high": {}, "medium": {}, "low": {} }
        },
        "claude-sonnet-4": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 64000 }
        },
        "claude-sonnet-4-thinking": {
          "name": "Claude Sonnet 4 (Thinking)",
          "limit": { "context": 200000, "output": 64000 }
        }
      }
    }
  },
  "plugin": ["oh-my-opencode@latest"]
}

Cline (VSCode)

В настройках расширения Cline выбери провайдера OpenAI Compatible:

  • Base URL: https://api.scarlex.ru/v1
  • API Key: YOUR_KEY
  • Model ID: claude-opus-4.7

Aider

aider \
  --openai-api-base https://api.scarlex.ru/v1 \
  --openai-api-key YOUR_KEY \
  --model claude-opus-4.7

Либо через переменные окружения OPENAI_API_BASE и OPENAI_API_KEY.

Ограничения

Прокси совместим с тремя протоколами: OpenAI Chat Completions, OpenAI Responses API (stateless) и Anthropic Messages API. Не поддерживается:

  • /v1/embeddings, /v1/images, /v1/audio — у апстрима (Anthropic Claude) этих моделей нет.
  • Vision (картинки во входе) — запросы с image / input_image content blocks отклоняются с 400.
  • Prompt caching (cache_control) — поле игнорируется (прокси не транслирует кеш-маркеры).
  • Server-side tools Anthropic (text_editor, bash, web_search, computer) — тихо отфильтровываются.
  • Server-side tools OpenAI Responses (web_search, file_search, code_interpreter, computer_use, image_generation) — тихо отфильтровываются.
  • Extended thinking (thinking) — поле игнорируется. Для reasoning используй модель claude-sonnet-4-thinking.
  • Stateful Responses API: previous_response_id возвращает 400, store: true игнорируется. Историю диалога передавай полностью в поле input.

Streaming (SSE)

Передай "stream": true. Ответ идёт построчно в формате Server-Sent Events:

data: {"id":"...","choices":[{"delta":{"content":"При"},"index":0}]}

data: {"id":"...","choices":[{"delta":{"content":"вет"},"index":0}]}

data: {"id":"...","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

OpenAI SDK обрабатывают это автоматически:

stream = client.chat.completions.create(
    model="claude-opus-4.7",
    messages=[{"role":"user","content":"Привет"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta: print(delta, end="", flush=True)

Tools / Function calling

Поддерживаются tools, tool_choice и tool_calls в формате OpenAI.

{
  "model": "claude-opus-4.7",
  "messages": [
    {"role":"user","content":"Какая погода в Москве?"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить погоду в городе",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

Модель отвечает массивом tool_calls. Выполни функцию и пришли результат обратно как сообщение с role: "tool" и тем же tool_call_id.

OpenAI Responses API (/v1/responses)

Stateless-реализация нового протокола OpenAI /v1/responses. Подходит для SDK и интеграций, которые уже перешли с chat.completions на client.responses.create().

Ограничения по сравнению с OpenAI:

  • previous_response_id → 400 Bad Request. Прокси не хранит ответы — передавай всю историю диалога в массиве input.
  • store: true принимается, но игнорируется (всё равно ничего не сохраняем).
  • reasoning — игнорируется. Для reasoning используй модель claude-sonnet-4-thinking.
  • Server-side tools (web_search, file_search, code_interpreter, computer_use, image_generation) тихо отфильтровываются.
  • input_image → 400 (vision не поддерживается).

Что работает: input как строка или массив items (message, function_call, function_call_output), instructions, function tools (flat и nested), stream: true с полным набором SSE-событий (response.created → response.output_text.delta → response.completed), биллинг по тем же множителям моделей.

cURL — простой вызов:

curl https://api.scarlex.ru/v1/responses \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.7",
    "input": "Привет!"
  }'

Python (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://api.scarlex.ru/v1",
)

resp = client.responses.create(
    model="claude-opus-4.7",
    instructions="Ты лаконичный ассистент.",
    input="Объясни замыкания в JS одним предложением.",
)
print(resp.output_text)

Streaming:

stream = client.responses.create(
    model="claude-opus-4.7",
    input="Расскажи короткую историю",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Function calling (плоский формат tools):

{
  "model": "claude-opus-4.7",
  "input": "Какая погода в Париже?",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Получить погоду в городе",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }]
}

Ответ содержит item с type: "function_call", call_id, name, arguments. Для следующего хода в input передаются: исходный user message → ассистентский function_call → function_call_output с тем же call_id.

Multi-turn (передаём историю целиком):

{
  "model": "claude-opus-4.7",
  "input": [
    {"type":"message","role":"user",
     "content":[{"type":"input_text","text":"Какая погода в Париже?"}]},
    {"type":"function_call","call_id":"call_1",
     "name":"get_weather","arguments":"{\"city\":\"Paris\"}"},
    {"type":"function_call_output","call_id":"call_1",
     "output":"{\"temp_c\":18,\"sky\":\"clear\"}"}
  ]
}

Endpoints

МетодПутьОписание
POST/v1/chat/completionsOpenAI Chat Completions. Поддерживает stream, tools, temperature, max_tokens.
POST/v1/responsesOpenAI Responses API (stateless). Stream, tools, instructions. См. раздел Responses API.
POST/v1/messagesAnthropic Messages API. Поддерживает stream, tools, multi-turn с tool_use/tool_result.
POST/v1/messages/count_tokensПриблизительный подсчёт токенов для Anthropic-формата.
GET/v1/modelsСписок доступных моделей в формате OpenAI.

Авторизация: Authorization: Bearer YOUR_KEY для OpenAI-совместимых клиентов, x-api-key: YOUR_KEY для Anthropic SDK / Claude Code. Поддерживаются оба варианта на любом эндпоинте.

Модели

Актуальный список моделей и цены — на странице Маркет. Программно получить список:

curl https://api.scarlex.ru/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

Параметры запроса

ПолеТипОписание
modelstringID модели (см. /v1/models).
messagesarrayМассив сообщений с role и content. Роли: system, user, assistant, tool.
temperaturenumber0..2. По умолчанию ~1.
max_tokensintegerЛимит токенов в ответе.
streambooleanВключить SSE-стриминг.
toolsarrayОписание функций для function calling.
tool_choicestring | object"auto", "none" или объект с именем функции.

Ошибки

КодЗначениеПричина
401UnauthorizedНеверный или отсутствующий API-ключ.
402Payment RequiredДостигнут лимит токенов ключа (hard_limit / tokens_limit). Пополни ключ.
429Too Many RequestsПревышен RPM ключа.
500Internal ErrorВнутренняя ошибка прокси.
502Bad GatewayОшибка апстрима Anthropic.
503Service UnavailableНет свободных аккаунтов в пуле. Повтори запрос через несколько секунд.

Лимиты

  • RPM — лимит запросов в минуту на ключ. Настраивается на странице Ключи.
  • tokens_limit — мягкий лимит токенов (предупреждение).
  • hard_limit — жёсткий лимит, после которого запросы возвращают 402.
  • Sticky sessions — в течение 20 минут запросы с одним ключом стараются попадать на тот же аккаунт пула (для лучшего cache hit).

FAQ

Поддерживается ли стриминг? Да, stream: true — формат OpenAI SSE.

Поддерживается ли vision (картинки на вход)? Нет, только текст.

Работает ли нативный Anthropic SDK / Claude Code? Да, через эндпоинт /v1/messages. Настройка: ANTHROPIC_BASE_URL=https://api.scarlex.ru.

Почему Opus дороже Haiku? К стоимости completion-токенов применяется множитель модели — таблица на странице Маркет.

Можно ли использовать function calling? Да, через tools и tool_choice в формате OpenAI.