API, совместимый с Anthropic: /v1/messages и ключевые контракты Claude Code

Чтобы позволить Claude Code использовать локальный шлюз, но не менять его использование протокола Anthropic, просто укажите Base URL на Antigravity Tools, а затем реализуйте один запрос с помощью /v1/messages.

Что такое API, совместимый с Anthropic?

API, совместимый с Anthropic относится к конечным точкам протокола Anthropic Messages, предоставляемым Antigravity Tools. Он принимает запросы /v1/messages, выполняет очистку пакетов, инкапсуляцию потока и ротацию повторов локально, а затем пересылает запрос на вышестоящий уровень, предоставляющий реальные возможности модели.

Чему вы научитесь

Реализовать Claude Code (или любой клиент Anthropic Messages) с помощью конечной точки /v1/messages Antigravity Tools
Разобраться в том, как настроить Base URL и заголовок аутентификации, чтобы избежать слепых попыток 401/404
При необходимости потока можно получить стандартный SSE; если не нужно, можно получить JSON
Знать, какие «исправления протокола» делает прокси в фоновом режиме (перехват warmup, очистка сообщений, обеспечение подписи)

Текущие проблемы

Вы хотите использовать Claude Code/Anthropic SDK, но сеть, аккаунты, квоты, лимитирование делают диалог нестабильным; вы уже запустили Antigravity Tools как локальный шлюз, но часто застреваете на этих проблемах:

Base URL написан как .../v1 или клиент «дублирует путь», что напрямую приводит к 404
Включили аутентификацию прокси, но не знаете, какой заголовок использует клиент для передачи key, в итоге 401
Фоновые задачи warmup/summary Claude Code тихо съедают квоту

Когда использовать этот метод

Вы хотите подключить Claude Code CLI и надеетесь, что он «по протоколу Anthropic» напрямую подключается к локальному шлюзу
Ваш клиент поддерживает только Anthropic Messages API (/v1/messages), и вы не хотите менять код

🎒 Подготовка

Предварительные условия

Этот урок предполагает, что вы уже реализовали базовый цикл локального прокси (можете получить доступ к /healthz, знаете порт прокси и включена ли аутентификация). Если ещё не реализовано, сначала прочитайте Запуск локального прокси и подключение первого клиента.

Вам нужно подготовить три вещи:

Адрес прокси (пример: http://127.0.0.1:8045)
Включена ли аутентификация прокси (и соответствующий proxy.api_key)
Клиент, который может отправлять запросы Anthropic Messages (Claude Code / curl подойдёт)

Основная идея

API, совместимый с Anthropic в Antigravity Tools соответствует набору фиксированных маршрутов: POST /v1/messages, POST /v1/messages/count_tokens, GET /v1/models/claude (см. определение Router в src-tauri/src/proxy/server.rs).

Среди них /v1/messages — это «главный вход», прокси перед фактической отправкой запроса на вышестоящий уровень выполнит кучу совместимых обработок:

Очистка полей, не принимаемых протоколом, в исторических сообщениях (например, cache_control)
Объединение последовательных сообщений одной роли, чтобы избежать неудачи проверки «чередование ролей»
Обнаружение пакетов warmup Claude Code и прямой возврат имитированного ответа, чтобы уменьшить трату квоты
Повтор и ротация аккаунтов на основе типа ошибки (до 3 попыток), чтобы повысить стабильность длинных сеансов

Пошаговое руководство

Шаг 1: Подтвердите, что Base URL написан только до порта

Зачем/v1/messages — это фиксированный маршрут на стороне прокси, написание Base URL как .../v1 легко приводит к тому, что клиент снова склеит /v1/messages, в итоге получится .../v1/v1/messages.

Вы можете сначала использовать curl для прямой проверки:

bash

#Что вы должны увидеть:{"status":"ok"}
curl -sS "http://127.0.0.1:8045/healthz"

Шаг 2: Если вы включили аутентификацию, сначала запомните эти 3 заголовка

Зачем Промежуточное ПО аутентификации прокси берёт key из Authorization, x-api-key, x-goog-api-key; если включена аутентификация, но заголовок не совпадает, будет стабильный 401.

Какие заголовки аутентификации принимает прокси?

Authorization: Bearer <key>, x-api-key: <key>, x-goog-api-key: <key> все можно использовать (см. src-tauri/src/proxy/middleware/auth.rs).

Шаг 3: Прямое подключение Claude Code CLI к локальному шлюзу

Зачем Claude Code использует протокол Anthropic Messages; указав его Base URL на локальный шлюз, можно повторно использовать этот контракт /v1/messages.

Настройте переменные среды по примеру README:

bash

export ANTHROPIC_API_KEY="sk-antigravity"
export ANTHROPIC_BASE_URL="http://127.0.0.1:8045"
claude

Что вы должны увидеть: Claude Code может нормально запуститься, и после отправки сообщения получить ответ.

Шаг 4: Сначала перечислите доступные модели (для curl/SDK)

Зачем Разные клиенты передадут model как есть; сначала получите список моделей, устранение неполадок будет намного быстрее.

bash

curl -sS "http://127.0.0.1:8045/v1/models/claude" | jq

Что вы должны увидеть: Возвращается JSON с object: "list", где data[].id — это доступные идентификаторы моделей.

Шаг 5: Используйте curl для вызова /v1/messages (непотоковый)

Зачем Это минимально воспроизводимая цепочка: без Claude Code тоже можно подтвердить, где именно ошибка в «маршрутизация + аутентификация + тело запроса».

bash

curl -i "http://127.0.0.1:8045/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-antigravity" \
  -d '{
    "model": "<выберите один из /v1/models/claude>",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Привет, кратко представься"}
    ]
  }'

Что вы должны видеть:

HTTP 200
В заголовке ответа может содержаться X-Account-Email и X-Mapped-Model (для устранения неполадок)
Тело ответа — это JSON в стиле Anthropic Messages (type: "message")

Шаг 6: При необходимости потока включите `stream: true`

Зачем Claude Code будет использовать SSE; вы также можете использовать curl для реализации потока SSE, подтверждая, что между ними нет проблем с прокси/буфером.

bash

curl -N "http://127.0.0.1:8045/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-antigravity" \
  -d '{
    "model": "<выберите один из /v1/models/claude>",
    "max_tokens": 128,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Объясни в 3 предложениях, что такое локальный прокси-шлюз"}
    ]
  }'

Что вы должны увидеть: Строки событий SSE (event: message_start, event: content_block_delta и т.д.).

Контрольные точки ✅

GET /healthz возвращает {"status":"ok"}
GET /v1/models/claude может получить data[].id
POST /v1/messages может вернуть 200 (непотоковый JSON или потоковый SSE, выберите один из двух)

Частые ошибки

1) Не пишите Base URL как `.../v1`

Пример Claude Code — ANTHROPIC_BASE_URL="http://127.0.0.1:8045", потому что маршрут на стороне прокси уже содержит /v1/messages.

2) Если включена аутентификация, но `proxy.api_key` пуст, будет прямой отказ

Когда аутентификация прокси включена, но api_key пуст, промежуточное ПО напрямую вернёт 401 (см. логику защиты в src-tauri/src/proxy/middleware/auth.rs).

3) `/v1/messages/count_tokens` в пути по умолчанию — это реализация-заглушка

Когда пересылка z.ai не включена, эта конечная точка напрямую вернёт input_tokens: 0, output_tokens: 0 (см. handle_count_tokens). Не используйте её для оценки реальных токенов.

4) Вы явно не включили поток, но видите, что сервер «внутри использует SSE»

У /v1/messages прокси есть совместимая стратегия: когда клиент не требует потока, сервер может внутри принудительно использовать поток и затем собрать результат в JSON и вернуть (см. логику force_stream_internally в handle_messages).

Итог урока

Чтобы Claude Code/клиент Anthropic работал, по сути нужно 3 вещи: Base URL, заголовок аутентификации, тело запроса /v1/messages
Чтобы «протокол работал + длинный сеанс стабилен», прокси очистит исторические сообщения, перехватит warmup и при неудаче повторит/ротирует аккаунты
count_tokens сейчас не может использоваться как реальный критерий (если вы не включили соответствующий путь пересылки)

Предпросмотр следующего урока

В следующем уроке мы изучим Нативный API Gemini: /v1beta/models и подключение конечных точек Google SDK.

Приложение: Справочник по исходному коду

Нажмите, чтобы раскрыть расположение исходного кода

Обновлено: 2026-01-23

Функция	Путь к файлу	Строки
Маршруты прокси: `/v1/messages` / `count_tokens` / `models/claude`	`src-tauri/src/proxy/server.rs`	120-193
Главный вход Anthropic: `handle_messages` (включая перехват warmup и цикл повторов)	`src-tauri/src/proxy/handlers/claude.rs`	240-1140
Список моделей: `GET /v1/models/claude`	`src-tauri/src/proxy/handlers/claude.rs`	1163-1183
`count_tokens` (возвращает 0, когда z.ai не включён)	`src-tauri/src/proxy/handlers/claude.rs`	1186-1210
Обнаружение и имитация ответа warmup	`src-tauri/src/proxy/handlers/claude.rs`	1375-1493
---	---	---
Очистка запроса: удаление `cache_control`	`src-tauri/src/proxy/mappers/claude/request.rs`	68-148
Очистка запроса: объединение последовательных сообщений одной роли	`src-tauri/src/proxy/mappers/claude/request.rs`	253-296
---	---	---

Ключевые константы:

MAX_RETRY_ATTEMPTS = 3: максимальное количество повторов для /v1/messages

Запуск с нуля

Что делать при возникновении ошибки

Руководство по обновлению без ошибок

Подключите вашу AI платформу

Обновите систему до производственного уровня

API, совместимый с Anthropic: /v1/messages и ключевые контракты Claude Code

Что такое API, совместимый с Anthropic?

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка

Основная идея

Пошаговое руководство

Шаг 1: Подтвердите, что Base URL написан только до порта

Шаг 2: Если вы включили аутентификацию, сначала запомните эти 3 заголовка

Шаг 3: Прямое подключение Claude Code CLI к локальному шлюзу

Шаг 4: Сначала перечислите доступные модели (для curl/SDK)

Шаг 5: Используйте curl для вызова /v1/messages (непотоковый)

Шаг 6: При необходимости потока включите `stream: true`

Контрольные точки ✅

Частые ошибки

1) Не пишите Base URL как `.../v1`

2) Если включена аутентификация, но `proxy.api_key` пуст, будет прямой отказ

3) `/v1/messages/count_tokens` в пути по умолчанию — это реализация-заглушка

4) Вы явно не включили поток, но видите, что сервер «внутри использует SSE»

Итог урока

Предпросмотр следующего урока

Приложение: Справочник по исходному коду

API, совместимый с Anthropic: /v1/messages и ключевые контракты Claude Code ​

Что такое API, совместимый с Anthropic? ​

Чему вы научитесь ​

Текущие проблемы ​

Когда использовать этот метод ​

🎒 Подготовка ​

Основная идея ​

Пошаговое руководство ​

Шаг 1: Подтвердите, что Base URL написан только до порта ​

Шаг 2: Если вы включили аутентификацию, сначала запомните эти 3 заголовка ​

Шаг 3: Прямое подключение Claude Code CLI к локальному шлюзу ​

Шаг 4: Сначала перечислите доступные модели (для curl/SDK) ​

Шаг 5: Используйте curl для вызова /v1/messages (непотоковый) ​

Шаг 6: При необходимости потока включите stream: true ​

Контрольные точки ✅ ​

Частые ошибки ​

1) Не пишите Base URL как .../v1 ​

2) Если включена аутентификация, но proxy.api_key пуст, будет прямой отказ ​

3) /v1/messages/count_tokens в пути по умолчанию — это реализация-заглушка ​

4) Вы явно не включили поток, но видите, что сервер «внутри использует SSE» ​

Итог урока ​

Предпросмотр следующего урока ​

Приложение: Справочник по исходному коду ​

API, совместимый с Anthropic: /v1/messages и ключевые контракты Claude Code

Что такое API, совместимый с Anthropic?

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка

Основная идея

Пошаговое руководство

Шаг 1: Подтвердите, что Base URL написан только до порта

Шаг 2: Если вы включили аутентификацию, сначала запомните эти 3 заголовка

Шаг 3: Прямое подключение Claude Code CLI к локальному шлюзу

Шаг 4: Сначала перечислите доступные модели (для curl/SDK)

Шаг 5: Используйте curl для вызова /v1/messages (непотоковый)

Шаг 6: При необходимости потока включите `stream: true`

Контрольные точки ✅

Частые ошибки

1) Не пишите Base URL как `.../v1`

2) Если включена аутентификация, но `proxy.api_key` пуст, будет прямой отказ

3) `/v1/messages/count_tokens` в пути по умолчанию — это реализация-заглушка

4) Вы явно не включили поток, но видите, что сервер «внутри использует SSE»

Итог урока

Предпросмотр следующего урока

Приложение: Справочник по исходному коду