Как мигрировать с OpenAI API на Anthropic API

Результат: после выполнения этой инструкции у вас будет рабочий маршрут миграции с OpenAI API на Anthropic API: сначала через OpenAI SDK compatibility для быстрого smoke-теста, затем через нативный Claude Messages API для боевого использования.

Практический вердикт: если вам нужно быстро проверить перенос, начните с режима совместимости OpenAI SDK. Если вы готовите продакшн, переходите на нативный Claude API: Anthropic прямо рекомендует его для полного набора функций, а совместимый слой описывает в первую очередь как мост для тестирования и сравнения моделей.

• ⏱️ Время: 45–120 минут для базовой миграции; дольше, если у вас есть JSON/schema-ответы, региональная маршрутизация или жёсткая обвязка SDK.
• 🎯 Сложность: средний.
• 💰 Стоимость: зависит от модели и маршрутизации; перед внедрением проверьте официальную страницу pricing. Для inference_geo=us документация Anthropic указывает множитель 1.1x на Claude 4.6+.
• 🛠️ Что потребуется: существующая интеграция OpenAI API, Anthropic API key, доступ из поддерживаемого региона, возможность менять base_url и модель, доступ к текущей документации Anthropic для выбора точного имени модели.
• 📌 Актуально на 2026-08-15: рекомендуемый Anthropic маршрут — POST https://api.anthropic.com/v1/messages с заголовками content-type: application/json, x-api-key и anthropic-version: 2023-06-01. В Python-репозиториях на дату проверки были видны anthropic-sdk-python 0.120.2 и openai-python v2.45.0 как контрольные точки для сравнения поведения.

Редакционное ограничение: в предоставленном source pack не зафиксированы актуальные имена моделей Claude и полный пример тела запроса из quickstart. Поэтому ниже показан проверяемый путь миграции и обязательные заголовки, а точное имя модели и текущее тело запроса нужно взять из официальной документации Anthropic на дату внедрения.

Какой путь миграции выбрать

Пошаговая миграция

1. Шаг 1. Зафиксируйте, какие OpenAI-функции использует ваш текущий код.

   Найдите инициализацию клиента, текущее имя модели и все специальные режимы ответа. Отдельно отметьте, если у вас задействованы strict, audio input, prompt caching, response_format, n > 1, logprobs или metadata.

   Проверьте и структуру сообщений. В режиме OpenAI SDK compatibility Anthropic поднимает system и developer сообщения в одно начальное system-сообщение, поэтому тон и поведение системного промпта могут измениться даже без ошибок транспорта.

   Ожидаемый результат: у вас есть список мест, которые можно быстро прогнать через совместимость, и список мест, где потребуется нативный Claude API.

2. Шаг 2. Переключите существующий OpenAI SDK-клиент на Anthropic endpoint.

   Для первого прохода не переписывайте приложение полностью. Anthropic документирует мостовой вариант: оставьте OpenAI client, замените base_url на https://api.anthropic.com/v1/, подставьте Anthropic API key и позже замените имя модели на Claude.

   from openai import OpenAI
   
   client = OpenAI(
       api_key='YOUR_ANTHROPIC_API_KEY',
       base_url='https://api.anthropic.com/v1/',
   )

   На этом шаге не трогайте остальную логику вызова: задача — проверить сам факт маршрутизации на Anthropic с минимальным числом изменений.

   Ожидаемый результат: транспортная часть запроса уходит уже в Anthropic, а не в OpenAI.

3. Шаг 3. Замените имя модели и выполните один простой тестовый запрос из вашего текущего кода.

   Подставьте актуальную модель Claude из текущей документации Anthropic и отправьте самый простой существующий запрос, который уже работает в вашем приложении. Не начинайте с цепочек, агентов или сложной схемы ответа: сначала нужен базовый сигнал, что перенос вообще проходит.

   Если здесь ломаются только специальные параметры из шага 1, это ожидаемо. Anthropic пишет, что слой совместимости нужен в первую очередь для тестирования и сравнения, а не как долгосрочная замена нативному API.

   Ожидаемый результат: вы получили первый ответ Claude через старый код или увидели конкретный список несовместимых параметров, которые надо убрать из OpenAI-совместимого пути.

4. Шаг 4. Перенесите боевой путь на нативный Claude Messages API.

   Для продакшна переведите основной маршрут на нативный REST API Anthropic. Базовый endpoint Claude API — https://api.anthropic.com, а рекомендуемая точка старта для проверки миграции — POST /v1/messages. В quickstart зафиксированы обязательные заголовки: content-type: application/json, x-api-key и anthropic-version: 2023-06-01.

   curl https://api.anthropic.com/v1/messages 
     --header 'content-type: application/json' 
     --header 'x-api-key: YOUR_ANTHROPIC_API_KEY' 
     --header 'anthropic-version: 2023-06-01' 
     --data @request.json

   {
     "model": "TAKE_CURRENT_CLAUDE_MODEL_FROM_DOCS",
     "messages": "TAKE_CURRENT_REQUEST_BODY_FROM_ANTHROPIC_QUICKSTART"
   }

   Если вы отказываетесь от OpenAI SDK полностью, переходите на официальный Anthropic SDK. По документации Anthropic, официальные SDK берут на себя авторизацию, форматирование запросов, обработку ошибок и streaming.

   Ожидаемый результат: успешный ответ имеет type: message и содержит usage.input_tokens и usage.output_tokens.

5. Шаг 5. Перенесите JSON/schema-ответы на Structured Outputs.

   Если ваша интеграция использует OpenAI-подобные JSON- или schema-ответы, не пытайтесь сохранить поведение через response_format в совместимом слое. Документация Anthropic отдельно указывает, что текущая нативная замена для таких сценариев — Structured Outputs через output_config.format.

   Также важно не опираться на старый переходный путь. В документации сказано, что прежний поток с output_format и beta-header относится к legacy transition behavior. Для новой миграции безопаснее сразу ориентироваться на актуальный Structured Outputs.

   Ожидаемый результат: у вас есть отдельный нативный путь для структурированных ответов, а не попытка протащить старый response_format через мост совместимости.

6. Шаг 6. Проверьте регион доступа и перенесите маршрутизацию данных только в нативный API.

   Перед релизом откройте страницу Supported regions и убедитесь, что Claude API доступен в вашей стране, регионе или территории. Это авторитетный список доступности по данным Anthropic.

   Если вам нужна маршрутизация по резидентности, работайте с inference_geo. Документация Anthropic пишет, что эта настройка поддерживается на first-party Claude API и Claude Platform on AWS, по умолчанию маршрут глобальный, а подтверждение маршрутизации можно увидеть в объекте usage ответа.

   Есть два ограничения, которые часто пропускают. Во-первых, inference_geo поддерживается только на Claude 4.6 и новее; на старых моделях запросы с ним возвращают 400. Во-вторых, OpenAI SDK compatibility endpoint не поддерживает inference_geo, поэтому переносите эту логику только после перехода на нативный Messages API.

   Не забудьте перепроверить цену. В pricing-документации Anthropic указано, что US-only inference через inference_geo=us использует множитель 1.1x для Claude 4.6+.

   Ожидаемый результат: вы понимаете, доступен ли Claude API в вашей географии, нужен ли вам отдельный маршрут по данным и как это скажется на стоимости.

7. Шаг 7. Зафиксируйте версии SDK и сверяйтесь с changelog перед выкладкой.

   Чтобы не смешать миграцию backend и поведение клиента, пингуйте конкретные версии библиотек. В качестве контрольной точки source pack фиксирует, что на дату проверки в репозитории anthropic-sdk-python была видна версия 0.120.2, а в репозитории openai-python — релиз v2.45.0.

   Эти значения не нужно воспринимать как вечный latest. Они нужны как опорные версии для сравнения поведения и аудита изменений. Перед продовым запуском перечитайте changelog репозитория Anthropic SDK и, если вы пока остались на мосте совместимости, changelog OpenAI SDK тоже.

   Ожидаемый результат: миграция воспроизводится в одном окружении, а расхождения объясняются API и параметрами, а не случайным обновлением зависимостей.

Как проверить, что всё работает

1. Отправьте тестовый запрос на POST /v1/messages через нативный Claude API.
2. Убедитесь, что ответ содержит type: message. Это базовый признак успешного прохождения запроса по рекомендованному Anthropic пути.
3. Проверьте наличие usage.input_tokens и usage.output_tokens. Документация Anthropic прямо указывает их как часть успешного ответа quickstart.
4. Если вы используете inference_geo, проверьте подтверждение маршрутизации в объекте usage. Точный ключ лучше перепроверить в актуальной документации data residency на дату релиза.
5. Если вы шли через OpenAI SDK compatibility, прогоните один и тот же короткий запрос через старый OpenAI-путь и через Anthropic-путь. Если отличается только поведение на ограниченных параметрах вроде response_format, n > 1 или logprobs, вы нашли ожидаемые места для нативной переработки, а не случайную транспортную ошибку.

Частые ошибки и исправления

• ❌ Ошибка: вы оставили response_format или рассчитываете на прежнюю schema-логику.
  ✅ Решение: переносите структурированные ответы на output_config.format в Structured Outputs. Старый поток с output_format и beta-header в документации описан как legacy transition behavior.
• ❌ Ошибка: после переноса поведение системного промпта изменилось без явной ошибки API.
  ✅ Решение: проверьте, не зависели ли вы от отдельного разделения system и developer. В режиме совместимости Anthropic поднимает их в одно начальное system-сообщение.
• ❌ Ошибка: запрос с inference_geo возвращает 400.
  ✅ Решение: убедитесь, что вы используете Claude 4.6+ и обращаетесь к нативному Claude API, а не к OpenAI SDK compatibility endpoint.
• ❌ Ошибка: интеграция не запускается из вашей инфраструктуры или аккаунта.
  ✅ Решение: перепроверьте страницу Supported regions. Claude API доступен только в перечисленных там странах, регионах и территориях.
• ❌ Ошибка: после включения US-only inference бюджет оказался выше ожидаемого.
  ✅ Решение: учтите, что для inference_geo=us документация Anthropic указывает множитель 1.1x на Claude 4.6+. Перед запуском ещё раз сверяйтесь с официальной pricing-страницей.

Безопасность и ограничения

• OpenAI SDK compatibility у Anthropic документирован в первую очередь как мост для тестирования и сравнения. Для долговременного продакшна Anthropic рекомендует нативный Claude API.
• Точные имена моделей, доступность функций и релизный ритм меняются. Перед внедрением перепроверьте выбранную модель и целевую версию SDK в официальной документации и changelog.
• Доступ к Claude API ограничен поддерживаемыми странами, регионами и территориями. Проверяйте это перед закупкой трафика и перед деплоем в новый регион.
• Маршрутизация по данным через inference_geo работает не везде и не для всех моделей. На старых моделях она вернёт 400, а в OpenAI SDK compatibility endpoint вообще не поддерживается.
• Цены зависят от модели, региона и настроек маршрутизации. Страница pricing — источник истины перед релизом; не опирайтесь на старые расчёты.
• Практическое ограничение этой инструкции: из-за неполного source pack здесь не зафиксированы актуальные имена моделей Claude и полный нативный request body из quickstart. Эти две позиции нужно проверить непосредственно перед внедрением.

Что делать дальше

• Если вам нужен чистый стартовый шаблон под Claude, откройте Как подключить Anthropic API: ключ, Messages API, curl, Python и Node.js.
• Если вы хотите быстро сопоставить старую клиентскую обвязку, посмотрите Как интегрировать OpenAI API в приложение (Python/JS).
• Если вы выбираете стек не только по совместимости, но и по экономике, сравните OpenAI API vs Anthropic API: сравнение по цене и качеству.
• Если после миграции вы хотите ускорить поддержку SDK-слоя, пригодится Как создать API-клиент с помощью AI.

Вопросы и ответы

Можно ли мигрировать без полного рефакторинга в первый день?

Да. Anthropic документирует мостовой путь: оставить OpenAI client, сменить base_url на https://api.anthropic.com/v1/, заменить API key и имя модели. Но для полного набора функций Anthropic рекомендует нативный Claude API.

Как понять, что миграция уже успешна?

Надёжная проверка — нативный POST /v1/messages с успешным ответом, где есть type: message и токены в usage.input_tokens и usage.output_tokens.

Что делать, если у меня JSON-ответы по схеме?

Переводите их на Structured Outputs через output_config.format. Документация Anthropic описывает старый поток с output_format и beta-header как legacy transition behavior.

Поддерживается ли data residency при миграции через OpenAI SDK compatibility?

Нет. По документации Anthropic, inference_geo не поддерживается в OpenAI SDK compatibility endpoint. Для data residency переходите на нативный Claude API.

Можно ли заранее зафиксировать цену миграции?

Только ориентировочно. Anthropic отдельно предупреждает, что цены нужно проверять на официальной pricing-странице, а US-only inference через inference_geo=us для Claude 4.6+ идёт с множителем 1.1x.

Источники

• OpenAI SDK compatibility – Claude Platform Docs
• Get started with Claude – Claude Platform Docs
• Structured outputs – Claude API Docs
• Data residency – Claude Platform Docs
• Supported regions – Claude Platform Docs
• Pricing – Claude API Docs
• API overview – Claude API Docs
• GitHub – anthropics/anthropic-sdk-python · GitHub
• anthropic-sdk-python/CHANGELOG.md at main · anthropics/anthropic-sdk-python · GitHub
• GitHub – openai/openai-python: The official Python library for the OpenAI API · GitHub
• openai-python/CHANGELOG.md at main · openai/openai-python · GitHub