Claude API из кода: ключ, первый вызов и отличия от OpenAI

Claude вызывается из кода двумя способами: через родной Messages API Anthropic или через OpenAI-совместимый Chat Completions. Напрямую из России не работает ни тот, ни другой, потому что Anthropic не обслуживает страну и берёт оплату картой в долларах. Через шлюз доступны оба формата, но Claude ведёт себя не как GPT: на моделях пятого поколения размышление включено по умолчанию, а на temperature, префилл и принудительный вызов инструмента API отвечает ошибкой.

Почему ключ Anthropic из России не получить

Ключ выпускается в Claude Console: аккаунт, пополнение баланса, кнопка Create key. Россия отсекается на первом шаге: её нет в списке стран, где работают продукты Anthropic (проверено 29.10.2026). С сентября 2025 года запрет распространяется и на компании, которые больше чем на 50% принадлежат фирмам из неподдерживаемых регионов, где бы их ни зарегистрировали (Anthropic, 04.09.2025).

Второе препятствие — оплата. Anthropic берёт деньги банковской картой и считает всё в долларах (прайс), а карты Visa российских банков с марта 2022 года за рубежом не работают (Visa).

Подписка claude.ai ключ не заменяет. По справке Anthropic API оплачивается отдельно от любого тарифа. Pro к API ничего не добавляет. Max и Team включают ежемесячные кредиты на API ($100 у Max 5x, $200 у Max 20x), но тратятся они в той же Claude Console и с теми же требованиями к стране (Anthropic).

Из России остаётся шлюз: к Anthropic обращается он, а вы платите ему. В altrouter баланс пополняется картой РФ, СБП или криптой, ключ ar-… выпускается в кабинете, запросы к Claude принимаются в обоих форматах. Что из Claude вообще работает из России — чат, приложение, подписка, — разобрано в статье Claude в России.

Messages и Chat Completions: один Claude, два протокола

Родной протокол Anthropic называется Messages API. Остальной рынок в основном говорит на Chat Completions, формате OpenAI: под него написаны библиотека openai, LangChain и большинство редакторов с полем «свой ключ». Форматы отличаются не только адресом.

Колонка Anthropic составлена по quickstart и справочнику Messages на 29.10.2026.

У Anthropic есть и собственный OpenAI-совместимый адрес https://api.anthropic.com/v1/. Документация называет его слоем для тестов и сравнения моделей, а не решением для продакшена. Большинство неподдерживаемых полей он молча игнорирует, включая response_format, seed и logprobs. Кэширование промпта через него не работает, текст размышлений не возвращается.

Chat Completions удобен, когда в коде уже стоит OpenAI SDK и вендора вы меняете одной строкой model. Messages нужен клиентам, которые говорят только на нём: SDK Anthropic и Claude Code. У altrouter /v1/messages работает с 27.10.2026, настройка Claude Code описана в отдельной статье.

Первый вызов через OpenAI SDK

Код под шлюз отличается от кода под OpenAI двумя строками: ключом и base_url, адресом, куда SDK отправляет запросы.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ALTROUTER_API_KEY"],
    base_url="https://api.altrouter.ai/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-5.5",
    max_tokens=2000,
    messages=[
        {"role": "system", "content": "Отвечай по-русски, коротко."},
        {"role": "user", "content": "Чем Messages API отличается от Chat Completions?"},
    ],
)

choice = resp.choices[0]
print(choice.message.content)
print("finish_reason:", choice.finish_reason)
print("токены:", resp.usage.prompt_tokens, "+", resp.usage.completion_tokens)
print("списано, $:", getattr(resp.usage, "cost", None))

После первого ответа посмотрите на три поля. finish_reason со значением length значит, что ответ упёрся в max_tokens и оборван. Если completion_tokens заметно больше видимого текста, в счёт попало размышление. cost показывает, сколько списано за запрос в долларах (логи и стоимость).

Id модели у шлюза и у Anthropic пишутся по-разному: у нас claude-sonnet-5.5 с точкой, у Anthropic claude-sonnet-5-5 через дефис (обзор моделей). Берите id из GET /v1/models или каталога, а не из чужих примеров.

Тот же запрос в формате Anthropic

SDK Anthropic подключается к шлюзу так же: ключ плюс адрес без /v1, путь /v1/messages библиотека добавит сама.

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ALTROUTER_API_KEY"],
    base_url="https://api.altrouter.ai",
)

msg = client.messages.create(
    model="claude-sonnet-5.5",
    max_tokens=2000,
    system="Отвечай по-русски, коротко.",
    messages=[
        {"role": "user", "content": "Чем Messages API отличается от Chat Completions?"},
    ],
)

for block in msg.content:
    if block.type == "text":
        print(block.text)
print("stop_reason:", msg.stop_reason)
print("токены:", msg.usage.input_tokens, "+", msg.usage.output_tokens)

Текст собирается циклом по блокам не случайно. У моделей пятого поколения размышление включено, и первым в content может прийти блок thinking: по умолчанию текст в нём пустой, но сам блок на месте (Anthropic). Код вида msg.content[0].text на таком ответе упадёт.

Вторая деталь — версия API 2026-10-21. На неё перешли Python-пакет anthropic 2.0.0 и TypeScript-пакет @anthropic-ai/sdk 1.0.0. Они отправляют ключ в заголовке Authorization: Bearer вместо x-api-key, а на temperature, top_p и top_k API отвечает 400 даже со значением по умолчанию (гайд по миграции). Если между вашим кодом и API стоит свой прокси, который читает только x-api-key, после обновления SDK он перестанет видеть ключ.

Что ломается при переносе кода с GPT на Claude

Первыми ломаются сэмплинг-параметры. Ручку разброса temperature и соседний top_p Claude 4.7 и новее принимают только со значением по умолчанию, на любое другое API отвечает 400. В версии 2026-10-21 ошибку даёт любое значение на любой модели (Anthropic). В нашем справочнике параметров Claude тоже отмечен как модель без сэмплинг-параметров. Уберите их из запросов к Claude, а разброс задавайте промптом.

Второй источник 400 — префилл: последним сообщением кладут начало ответа ассистента, например {, чтобы модель продолжила JSON. На Claude 4.6 и новее такой запрос отклоняется (Anthropic).

JSON-режим OpenAI у Claude не срабатывает. Поле response_format совместимый слой Anthropic молча пропускает, а у нас для моделей Claude он не поддерживается (справочник). В формате OpenAI валидный JSON получают через вызов инструмента со схемой аргументов, пошагово это разобрано в статье про tool calling. В нативном API для этого есть output_config.format со схемой (Anthropic).

Принудительный вызов инструмента на новых моделях тоже недоступен. tool_choice: "required" или имя конкретной функции на Opus 5.5, Sonnet 5.5 и Fable 5.1 возвращают ошибку: эти модели не умеют вызывать инструмент принудительно (Anthropic). Ставьте "auto", а в промпте опишите, когда инструмент нужен.

Последнее — потолок ответа. В Messages max_tokens обязателен, и размышления расходуют тот же лимит, что и видимый ответ. Через наш шлюз Claude сверяет max_tokens с потолком вывода модели и отвечает 400, если запрошено больше (справочник). Потолок указан на странице модели в каталоге.

Остальные отличия ошибок не вызывают, но меняют поведение. Совместимый слой Anthropic собирает все сообщения system в одну инструкцию в начале диалога, где бы они ни стояли. Поле n там должно быть равно 1, а seed, штрафы за повторы и logprobs пропускаются без ошибки. Что делать с кодами, которые всё-таки пришли, — в разборе ошибок Claude API.

Размышление включено по умолчанию и оплачивается как ответ

Модели пятого поколения, прежде чем ответить, пишут черновик: это токены размышлений. У Anthropic черновик включён без всякого параметра. Его токены оплачиваются по цене выхода, даже когда текст вам не возвращают, и входят в max_tokens (Anthropic).

Глубину размышления задаёт output_config.effort — ручка с уровнями от low до max. По умолчанию стоит high, у Opus 5.5 и Haiku 5.5 — medium (Anthropic). Чем ниже уровень, тем меньше токенов уходит на черновик и тем дешевле ответ.

Через наш Chat Completions размышлением у Claude управляет reasoning_effort, и для Claude он работает как выключатель: любое значение включает размышление (справочник параметров). У Opus 5.5 и Fable 5.1 выключить его не выйдет ни у Anthropic, ни через шлюз, потому что это свойство модели. Насколько черновик увеличивает счёт и как его измерить, разобрано в статье сколько стоит Claude API.

Какую модель ставить в model

У Anthropic четыре актуальные модели, остальные числятся устаревшими (legacy), но работают (обзор моделей, 29.10.2026):

Если сомневаетесь, Anthropic советует начинать с Opus 5.5. Проверять модели дешевле снизу вверх: прогоните 20–50 своих реальных запросов на Haiku 5.5, и если ответы устраивают, платить за старшие модели незачем.

Разница между ступенями измеряется разами. Запрос в 2 000 токенов входа и 500 выхода без учёта размышления на Haiku 4.5 у нас стоит $0,0035, на Opus 4.8 — $0,020, почти вшестеро дороже. Между Haiku 5.5 и Opus 5.5 разрыв сорокакратный: $0,00038 против $0,0153. Цены взяты из каталога altrouter на 27.10.2026. Полный прайс, кэш и расчёт на сценариях — в статье сколько стоит Claude API.

Со старыми id связаны две ловушки. Первая — сроки. claude-sonnet-4-5 Anthropic снимает 30.11.2026 и предлагает замену claude-sonnet-5-5. У Haiku 4.5 обещанный срок «не раньше 15.10.2026» уже прошёл, у Opus 4.5 он истекает 24.11.2026 (график снятия моделей). Вторая — наш минус: в каталоге altrouter у Opus 4.6–4.8, Sonnet 4.6, Sonnet 5 и Fable 5 указан контекст 200K, хотя Anthropic с поколения 4.6 даёт 1M (прайс). Для длинного контекста через шлюз берите модели 5.5, Opus 5 или Fable 5.1, у них в каталоге 1M.

FAQ