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

1Базовый URL

https://sunagent.net

Все API-эндпоинты живут под этим корнем: /v1/messages, /v1/models и так далее.

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

Ключ можно передать одним из двух способов:

# Anthropic-стиль (рекомендуется — совместимо с их SDK)
x-api-key: vb-live-xxxxxxxx

# Bearer-стиль
Authorization: Bearer vb-live-xxxxxxxx

3Эндпоинты

4Модели · строгий allow-list

Модель, которой нет в GET /v1/models, всегда возвращает 400 unknown_model. Никаких молчаливых подмен. Если попросить несуществующее имя — получите ошибку, а не тихую замену на другую модель.

Разрешены только dated-алиасы (Anthropic-стандарт), например:

claude-opus-4-5      → claude-opus-4-5-20251101
claude-haiku-4-5     → claude-haiku-4-5-20251001

Это семантически один и тот же билд; сервер сигнализирует про раскрытие заголовком X-Upstream-Model-Dated-Alias: true.

Текущий список: opus-4-8, opus-4-7, opus-4-6, opus-4-5, sonnet-5, sonnet-4-6, haiku-4-5, 3-opus-20240229.

5Тарификация и max_tokens

Списание — по факту токенов, отчёт в кабинете и в /v1/usage сразу после запроса. Счётчики input_tokens/output_tokens берутся из ответа самого Claude (upstream final usage). Курс топ-апа: 90 ₽ ≈ $1.

max_tokens строго соблюдается. Как только output достигает лимита, стрим обрезается, финальный чанк выставляет stop_reason=max_tokens, и на ответе появляется заголовок X-Max-Tokens-Enforced: N.

Тарифы см. на главной. Для админ-аккаунтов может стоять флаг unlimited — списаний нет.

6Extended thinking

Поддерживается стандартный Anthropic-параметр thinking:

{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "thinking": { "type": "enabled", "budget_tokens": 1024 },
  "messages": [{"role":"user","content":"..."}]
}

Если модель не поддерживает thinking — сервер автоматически перерутит запрос на ближайшую подходящую и вернёт заголовок X-Thinking-Model-Rerouted: true.

7Tool use / function calling

Поддерживается стандартный Anthropic-контракт: клиент шлёт tools и tool_choice, сервер возвращает content: [{"type":"tool_use",...}] и stop_reason: "tool_use". Работает во всех моделях — opus, sonnet, haiku.

Пример запроса с forced tool_choice:

{
  "model": "claude-opus-4-8",
  "max_tokens": 300,
  "tools": [{
    "name": "emit",
    "description": "Emit the composed email",
    "input_schema": {
      "type": "object",
      "properties": {
        "subject": {"type": "string"},
        "body":    {"type": "string"}
      },
      "required": ["subject", "body"]
    }
  }],
  "tool_choice": {"type": "tool", "name": "emit"},
  "messages": [{"role":"user","content":"Write a 1-sentence cold email."}]
}

Ответ (валидный Anthropic-shape, stop_reason=tool_use):

{
  "content": [{
    "type": "tool_use",
    "id":   "toolu_01a4b5c...",
    "name": "emit",
    "input": {"subject": "...", "body": "..."}
  }],
  "stop_reason": "tool_use",
  "usage": {...}
}

Поддерживаемые режимы tool_choice:

• {"type":"auto"} — по умолчанию, модель сама решает
• {"type":"any"} — обязана вызвать один из tools
• {"type":"tool","name":"X"} — обязана вызвать именно X
• {"type":"none"} — запрещено вызывать tools
• Строковые формы "auto" / "any" / "none" тоже принимаются

Multi-turn с tool_result: клиент может слать в messages историю с role:"assistant" + content:[{"type":"tool_use",...}] и следующим role:"user" + content:[{"type":"tool_result","tool_use_id":"...","content":"..."}]. Мы конвертируем эти блоки в человекочитаемый текст перед отправкой в upstream, так что модель видит консистентный контекст.

Ограничение: JSON внутри input валидируется best-effort. Если модель выдала что-то нечитаемое, приходит заголовок X-Tool-Use-Parse-Failed: true и ответ вернётся в text-режиме — с исходным <tool_use> тегом в тексте. На практике на opus/sonnet парсинг успешен >99% запросов.

Streaming: если запрошен stream:true + tools — прокси буферизирует ответ upstream внутренне (чтобы отпарсить sentinel), а клиенту отдаёт нормальный SSE-поток с content_block_start(tool_use) + input_json_delta + content_block_stop. То есть SDK-клиенты видят полностью совместимую последовательность событий, но TTFB для tool-запросов равен полному времени ответа модели.

8Prompt caching · не поддерживается

Что это значит для клиента:

• Запрос с cache_control в system/messages НЕ вернёт 400 — блоки просто игнорируются.
• В usage всегда возвращается cache_creation_input_tokens: 0 и cache_read_input_tokens: 0 — числа, не null.
• Заголовок ответа: X-Cache-Support: none.
• Полный input считается по факту каждый раз — как обычный некешированный вход.

Если в будущем появится upstream с нативным кешем — включим прозрачно и обновим заголовок на X-Cache-Support: native.

9Rate-limit и ошибки

• Персональных rate-limit нет — тормозит только исчерпание баланса (402 insufficient_balance).
• Пул из 15 upstream-аккаунтов + до 3 автоматических retry на 502/429/500/503/504/401/403.
• Долгие стримы дропаются nginx через 600 секунд (proxy_read_timeout).
• Полная политика в JSON: /v1/limits

10Аудит-заголовки на каждом ответе

11Готовые интеграции

export ANTHROPIC_BASE_URL="https://sunagent.net"
export ANTHROPIC_AUTH_TOKEN="vb-live-..."
claude

from anthropic import Anthropic
c = Anthropic(
  base_url="https://sunagent.net",
  api_key="vb-live-...",
)

curl https://sunagent.net/v1/messages \
  -H "x-api-key: vb-live-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6",
       "max_tokens":256,
       "messages":[{"role":"user","content":"привет"}]}'