OpenAI‑совместимый API: base URL, Python и ошибки

Как правильно задать base URL, ключ и модель?

Уточните, ожидает ли ваш клиент базовый адрес или уже полный маршрут. В примере ниже base URL заканчивается на /v1, а скрипт добавляет /chat/completions сам. Поэтому в переменную нельзя записывать полный маршрут: иначе он повторится.

На первом тесте используйте обычный текст без изображений, инструментов и необязательных параметров. Так проще отделить ошибку адреса или ключа от неподдерживаемой функции. Если вы ещё выбираете провайдера, используйте матрицу выбора AI API.

Минимальный запрос на Python без SDK

Этот пример использует стандартную библиотеку Python 3. Адрес ниже — условный пример, а рабочий адрес и имя модели нужно получить у выбранного провайдера. Задайте AI_BASE_URL, AI_API_KEY и AI_MODEL в окружении своего процесса. Не вставляйте секрет в код или публичную команду.

import json
import os
import urllib.error
import urllib.request
from urllib.parse import urlsplit

base_url = os.environ["AI_BASE_URL"].rstrip("/")
api_key = os.environ["AI_API_KEY"].strip()
model = os.environ["AI_MODEL"]
if urlsplit(base_url).scheme != "https":
    raise ValueError("Use the provider's HTTPS base URL")
if not api_key:
    raise ValueError("AI_API_KEY is empty")

payload = {
    "model": model,
    "messages": [{"role": "user", "content": "Ответь: тест успешен"}],
    "stream": False,
}
request = urllib.request.Request(
    base_url + "/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=45) as response:
        result = json.load(response)
    print(result["choices"][0]["message"]["content"])
except urllib.error.HTTPError as error:
    print("HTTP status:", error.code)
    print("Request ID:", error.headers.get("x-request-id", "not provided"))
except urllib.error.URLError:
    print("Check DNS, TLS, network access and timeout")

Скрипт предполагает стандартный ответ Chat Completions с choices. Если получен HTTP 200, но нужного поля нет, изучите обезличенную структуру ответа: возможно, маршрут возвращает другой формат. Не публикуйте полный запрос с заголовком авторизации.

Что означают ошибки API 401, 403, 404 и 429?

Коды и тексты ошибок у сторонних API могут отличаться. Диагноз подтверждают по request ID и журналу провайдера. Бесконечные повторы не исправят ошибку ключа или исчерпанный бюджет. Подробнее о расходах — в руководстве по квотам и стоимости.

Что отправить для диагностики?

Версию клиента, путь без секретных параметров, модель, время с часовым поясом, HTTP‑код и request ID. API‑ключ, пароли и содержимое закрытого проекта не нужны. Правила хранения ключей — в чек‑листе безопасности.

Почему короткий запрос работает, а агент или streaming — нет?

Короткий текстовый ответ проверяет только небольшой участок протокола. Для streaming нужно проверить формат событий и завершение потока; для tools — JSON‑аргументы, ID вызовов и продолжение диалога после результата инструмента. Неподдерживаемое поле может проявиться только во втором раунде.

Сначала сравните обычный и потоковый ответ одной модели, затем добавьте один инструмент. Зафиксируйте задержку первого события, время полного ответа, usage и ошибки. Для IDE‑агентов используйте отдельную матрицу coding‑клиента: возможности конкретного клиента могут отличаться от обычного API‑чата.

Чек‑лист перед интеграцией в продукт

1. Записать точные base URL, протокол и ID модели.
2. Создать тестовый ключ с ограниченным бюджетом.
3. Пройти короткий запрос, streaming и нужные инструменты.
4. Проверить сетевой доступ из страны и окружения будущего продукта.
5. Измерить задержку и стоимость успешной задачи.
6. Уточнить обработку данных и журналы.
7. Сохранить рабочую конфигурацию и способ отката.

Для команды из России важно проверять фактические условия доступа выбранного провайдера, а не обещание «работает везде». Время ответа зависит от вашей сети и маршрута; его нельзя надёжно оценить по чужому скриншоту.

Частые вопросы об OpenAI‑совместимом API

Можно ли заменить только base URL?

Иногда да, но отдельно сверяют ключ, модель и функции. Если приложение вызывает Responses, а провайдер поддерживает только Chat Completions, одной замены адреса недостаточно.

Подойдёт ли ключ от другого сервиса?

Не следует это предполагать. Используйте ключ и адрес, которые провайдер явно указал как совместимую пару.

Что делать, если я не знаю модель или нагрузку?

Опишите задачу и текущий клиент. Оценку можно начать с небольшого пилота; точный объём запросов не обязателен для первого разговора.