ДокументацияНастройка клиентовОбщая настройка клиентов

Общая настройка клиентов

Подключение универсальных AI-клиентов к SoleAPI через поддерживаемый клиентом протокол.

Общая настройка клиентов

Если клиент поддерживает Anthropic Messages, OpenAI Responses или OpenAI Chat Completions, его можно подключить к SoleAPI по этому руководству. Названия настроек различаются, но главное — выбрать правильный протокол и направить запросы на соответствующую точку входа. Сейчас у SoleAPI меньше источников для OpenAI Chat Completions; подтверждена работа OpenAI (GPT) и xAI (Grok).

Перед началом создайте API Key, убедитесь, что он включает группу целевой модели, и скопируйте идентификатор модели из каталога моделей.

Совместимость протокола означает, что запросы и ответы соответствуют его формату. Она не означает, что каждая модель поддерживает все возможности протокола. Успешный текстовый запрос также не гарантирует поддержку инструментов, изображений, рассуждений, кэширования и других расширений.

Сначала определите тип поля клиента

В настройках пользовательской модели, провайдера или подключения найдите тип протокола, Base URL (или API Endpoint), API Key и идентификатор модели. Одни клиенты ожидают базовый адрес, другие — полный URL запроса. Перед вводом определите, какой вариант требуется.

Как клиент добавляет путьAnthropic MessagesOpenAI ResponsesOpenAI Chat Completions
Клиент добавляет /v1/messageshttps://soleapi.comНе применяетсяНе применяется
Клиент добавляет /messages, /responses или /chat/completionshttps://soleapi.com/v1https://soleapi.com/v1https://soleapi.com/v1
Клиент ожидает полный URL запросаhttps://soleapi.com/v1/messageshttps://soleapi.com/v1/responseshttps://soleapi.com/v1/chat/completions
API KeyAPI Key SoleAPIAPI Key SoleAPIAPI Key SoleAPI
Идентификатор моделиID из каталога моделейID из каталога моделейID из каталога моделей

Используйте либо базовый адрес, либо полный URL запроса. Не вводите https://soleapi.com/v1/messages, https://soleapi.com/v1/responses или https://soleapi.com/v1/chat/completions в поле Base URL, которое автоматически добавляет соответствующий путь. Также не вводите https://soleapi.com/v1 в поле, ожидающее полный URL. Иначе /v1 или путь протокола продублируется. Учитывайте правила добавления пути конкретным клиентом или provider.

Вариант 1: Anthropic Messages

Выберите в клиенте Anthropic, Anthropic Messages или эквивалентный протокол:

  • Если клиент добавляет /v1/messages, укажите https://soleapi.com.
  • Если клиент добавляет /messages, укажите https://soleapi.com/v1.
  • Если требуется полный URL, укажите https://soleapi.com/v1/messages.
  • API Key: укажите Key, созданный в консоли SoleAPI.
  • Идентификатор модели: укажите ID из каталога моделей.
  • Аутентификация: если её можно выбрать, используйте Anthropic API Key или вариант x-api-key.

Обычно клиент автоматически отправляет заголовки x-api-key, anthropic-version и другие. В поле API Key вводите только сам Key, не добавляя префикс Bearer вручную.

Эта конфигурация использует точку входа SoleAPI POST /v1/messages. Поля и примеры запросов приведены в разделе Messages API.

Вариант 2: OpenAI Responses

Выберите в клиенте OpenAI Responses, Responses API или эквивалентный протокол:

  • Если клиент добавляет /responses, укажите https://soleapi.com/v1.
  • Если требуется полный URL, укажите https://soleapi.com/v1/responses.
  • API Key: укажите Key, созданный в консоли SoleAPI.
  • Идентификатор модели: укажите ID из каталога моделей.
  • Аутентификация: если её можно выбрать, используйте OpenAI Bearer Token или эквивалентный вариант.

Клиент должен автоматически отправлять заголовок Authorization: Bearer <API Key>. Обычно в поле API Key вводится только сам Key; при отличиях следуйте подсказкам клиента.

Эта конфигурация использует точку входа SoleAPI POST /v1/responses. Поля и примеры ответов приведены в разделе Responses API.

Вариант 3: OpenAI Chat Completions

Выберите OpenAI Chat Completions, OpenAI Compatible или эквивалентный протокол. Некоторые клиенты называют его просто OpenAI; убедитесь, что фактически используется Chat Completions, а не Responses:

  • Если клиент добавляет /chat/completions, укажите https://soleapi.com/v1.
  • Если клиент добавляет /v1/chat/completions, укажите https://soleapi.com.
  • Если требуется полный URL, укажите https://soleapi.com/v1/chat/completions.
  • API Key: укажите Key, созданный в консоли SoleAPI.
  • Идентификатор модели: укажите ID из каталога моделей.
  • Аутентификация: выберите OpenAI Bearer Token или эквивалентный вариант, чтобы клиент автоматически отправлял Authorization: Bearer <API Key>.

Эта конфигурация использует точку входа SoleAPI POST /v1/chat/completions. Сейчас подтверждены источники OpenAI (GPT) и xAI (Grok). Многие китайские модели сами поддерживают этот протокол, но SoleAPI пока не добавил соответствующие источники.

Выберите протокол по провайдеру

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

Эта таблица является основным источником сведений о соответствии провайдеров и протоколов и здесь не дублируется. При настройке также используйте ID из каталога моделей и проверьте модели, доступные текущему API Key.

Особая проверка OpenCode

Встроенный Anthropic provider OpenCode использует baseURL как префикс /v1, а затем добавляет /messages. Поэтому в нативной конфигурации Anthropic для OpenCode укажите:

json
{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://soleapi.com/v1"
      }
    }
  }
}

Не определяйте протокол только по надписям «OpenAI» или «Compatible» в интерфейсе. Если OpenCode использует @ai-sdk/openai-compatible, запросы обычно идут на /v1/chat/completions; это не Anthropic Messages. Для вызова /v1/messages используйте Anthropic provider OpenCode или другой provider, который явно использует Anthropic Messages.

Фактический путь запроса позволяет быстро определить протокол:

  • /v1/messages: Anthropic Messages; затем проверьте инструменты и расширенные поля в теле запроса.
  • /v1/responses: OpenAI Responses; затем убедитесь, что клиент использует Responses provider.
  • /v1/chat/completions: OpenAI Chat Completions; сейчас в SoleAPI подтверждены источники GPT и Grok, но источники соответствующих китайских моделей ещё не добавлены.
  • /messages: обычно в Base URL отсутствует /v1; добавьте его с учётом правил клиента.

Текущая область OpenAI Chat Completions в SoleAPI

POST /v1/chat/completions сохранён как устаревшая точка входа для совместимости и не рекомендуется как первый вариант для новых интеграций. OpenAI (GPT) и xAI (Grok) сейчас могут его использовать. Многие китайские модели также сами поддерживают Chat Completions, но SoleAPI пока не добавил соответствующие источники, поэтому через этот протокол они сейчас недоступны.

Это не означает, что китайские модели не поддерживают Chat Completions или вообще недоступны. Проверьте каталог моделей и список моделей текущего API Key, затем выберите протокол, который сейчас доступен в SoleAPI. Для китайских моделей можно использовать доступную точку входа Messages или Responses.

Проверка и сохранение

Сохраните конфигурацию и сначала отправьте простой текстовый запрос. После успешного базового запроса отдельно проверьте инструменты, потоковую передачу, изображения, рассуждения и другие возможности.

Проверяйте в следующем порядке:

  1. Убедитесь, что идентификатор модели указан правильно и её группа доступна текущему API Key.
  2. Сопоставьте протокол и путь: Messages использует /v1/messages, Responses — /v1/responses, Chat Completions — /v1/chat/completions.
  3. Убедитесь, что Base URL не перепутан с полным URL запроса.
  4. Сначала проверьте заведомо рабочую модель, затем переключитесь на целевую.
  5. После успешного текста отдельно проверьте расширенные возможности, например вызов инструментов.

Почему один протокол работает по-разному в разных клиентах?

«Поддерживает Anthropic Messages» означает лишь, что клиент способен создать запрос в формате Messages. Клиенты всё равно могут различаться:

  • По-разному добавлять путь и отправлять запросы на /messages, /v1/messages или /v1/chat/completions.
  • Отправлять разные заголовки аутентификации, anthropic-version или anthropic-beta.
  • Автоматически добавлять определения инструментов, tool_choice, системные инструкции и более длинный контекст.
  • Включать кэширование промптов, параметры рассуждений, изображения или определённые потоковые события.
  • По-разному разбирать вызовы инструментов, потоковые события и ошибки.

Успешный обычный диалог в одном клиенте доказывает только, что модель обработала этот конкретный запрос. Он не гарантирует совместимость с полным агентным процессом другого клиента. Например, если GLM возвращает текст через Anthropic Messages в одном клиенте, но завершается ошибкой в другом клиенте для программирования, сначала проверьте, не добавляет ли второй инструменты или другие расширенные поля, и только затем ищите проблему в точке входа модели.

Устранение неполадок

  • 404 или точка входа не найдена: сопоставьте протокол и путь. Messages использует /v1/messages, Responses — /v1/responses, Chat Completions — /v1/chat/completions.
  • Путь содержит /v1/v1/messages, /v1/v1/responses, повторный /v1 или повторный путь протокола: Base URL уже содержит версию либо клиент добавляет её автоматически. Используйте базовый адрес, соответствующий фактическому поведению клиента.
  • 401: проверьте, что API Key указан полностью, активен и не истёк, а способ аутентификации соответствует протоколу.
  • 403: проверьте, что API Key включает группу целевой модели. Если включён белый список IP, добавьте IP текущего устройства.
  • Текст работает, но вызов инструментов завершается ошибкой: обычно базовый протокол работает, но модель или вышестоящая точка входа не принимает параметры инструментов клиента. Отключите инструменты или сравните с моделью, для которой их поддержка подтверждена.
  • Один клиент работает, другой нет: сравните фактические пути, заголовки и тела запросов. Проверяйте определения инструментов, tool_choice, поля рассуждений и кэширования, а также потоковые события, а не только названия протоколов в настройках.
  • Модель не найдена или нет доступной точки входа: сверьте ID с каталогом моделей и убедитесь, что модель доступна текущему API Key. Если Chat Completions не работает для китайской модели, сначала учтите, что SoleAPI пока не добавил соответствующий источник, а не делайте вывод об отсутствии поддержки протокола самой моделью; используйте доступную точку входа Messages или Responses.