# z ai api и совместимость GLM: как изолировать контракт в адаптере

Source: https://provod.ai/ru/blog/api150-a064-z-ai

Ты выяснил, что за строкой `z ai api` стоит Zhipu и модельная линейка GLM. Это меньше половины работы. Идентифицировать владельца эндпоинта - значит закрыть вопрос «чей это API», но не вопрос «как его особенности не прорастут в мой прикладной код». Именно на втором шаге интеграция ломается тихо: синтаксис совместим с OpenAI, тесты локально зелёные, а поведение на границе поставщика отличается от того, что ты заложил в домен.

Это разбор контракта, а не обзор сервиса. Дальше три вещи по порядку: развести идентификацию поставщика и поведенческий контракт, показать три типа контрактного теста для одного сценария, объяснить, где проходит граница адаптера. Всё ниже опирается на официальную документацию Z.AI на 18 июля 2026 - адаптерного кода и логов прогона у меня пока нет, есть метод и документированная поверхность API.

Умолчание, из-за которого горят сроки, звучит так: «совместимый синтаксис гарантирует одинаковое поведение». Не гарантирует. Ниже - конкретные места, где документация расходится с ожиданиями от OpenAI-совместимого клиента, и метод, который вылавливает их до релиза, а не в проде. Оговорка для тех, кто ещё выбирает поставщика: если возиться с регионами и планами не хочется вовсе, [provod.ai (российский аналог OpenRouter)](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a064-z-ai&utm_content=hook&utm_id=brief-a064) отдаёт один совместимый маршрут сразу к нескольким моделям - но адаптер и тесты всё равно писать тебе, ровно по тем же причинам.

[Платите в рублях за AI-модели без наценки на токены через provod.ai](https://provod.ai/?ref=blog-cta-top&utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a064-z-ai)

## Почему знать владельца z ai api - это только полдела?

Разработчик, который дошёл до этой статьи, обычно уже прошёл этап идентификации. Он видел запросы вроде `glm ai api`, `zhipu ai api` и понял, что это один и тот же поставщик под разными именами: Z.AI как международный бренд, Zhipu (BigModel) как исходное имя, GLM как семейство моделей. Знание полезное, но оно отвечает на вопрос «кто», а прикладной риск живёт в вопросе «как».

Скрытая связанность проникает в код незаметно. Ты пишешь обработчик ответа, который читает `reasoning_content`, потому что видел его в одном ответе. Ты ловишь ошибку и парсишь её как `error.message`, по привычке от OpenAI. Ты хардкодишь один base URL, потому что первый же запрос прошёл. Каждое из этих решений связывает доменную логику с конкретным поведением GLM-клиента, и ни одно из них не видно из синтаксиса запроса. Через полгода Z.AI меняет умолчание для новой версии модели, и падает не клиент, а бизнес-правило где-то в глубине домена.

Правило, которого я держусь: доменная логика не должна знать имя поставщика. Она формулирует намерение - «дай ответ по этому промпту, обработай отказ» - а перевод намерения в диалект Z.AI живёт в одном изолированном месте. Это не факт из документации, а инженерная ставка. Ставку надо проверять тестами, а не декларировать.

## Какой именно endpoint? Три URL для одного аккаунта

Первое, что ломает наивную интеграцию, - предположение, что у `z ai api` один адрес. Его нет. По документации Z.AI на 18 июля 2026 общий эндпоинт чат-комплишенов - это `POST https://api.z.ai/api/paas/v4/chat/completions` с заголовком `Authorization: Bearer YOUR_API_KEY`. Но официальный Python-SDK (`zai-org/z-ai-sdk-python`) не задаёт единого base URL по умолчанию: разработчик обязан явно выбрать между зарубежным `https://api.z.ai/api/paas/v4/` и материковым `https://open.bigmodel.cn/api/paas/v4/`. То есть «эндпоинт» без указания региона - это не один подтверждённый факт, а два.

Третий адрес появляется отдельно. Подписки GLM Coding Plan используют выделенные base URL, отличные от общего: `https://api.z.ai/api/coding/paas/v4` в стиле OpenAI Chat Completions и `https://api.z.ai/api/anthropic` в стиле Anthropic Messages. Ключи Coding Plan привязаны к своей экосистеме и не работают против общего `/api/paas/v4`. Все три варианта пришлось собирать с трёх разных официальных страниц: ни одна не сводит их вместе. Сверку делаешь ты сам, до первого теста.

Вопрос «какой url» задают так часто, что он доходит даже в сломанной раскладке - `rfrjq url api z ai`. Корректный ответ на него один и тот же: зависит от типа аккаунта и региона. Ошибка здесь дорогая не потому, что её трудно найти, а потому, что она всплывает на шаге, где всё уже выглядело готовым к запуску.

Про `z ai api free` честно: тарифы, пороги квот и бесплатные лимиты проверенные источники этого материала не покрывают. Проверенного числа у меня нет, а выдумывать его я не стану - смотри актуальные условия на день интеграции.

![Маршрутная схема: один аккаунт Z.AI и три разных base URL в зависимости от региона и плана.](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/02-163.png)

## Три контрактных теста: обычный ответ, ошибка, конфигурация

Метод, который я предлагаю, - контрактный набор по формуле «сценарий - ожидание - адаптер - наблюдение». Берём один GLM-сценарий и пишем для него три теста разной природы: на обычный ответ, на ошибку, на модельную конфигурацию. Смысл не в покрытии всех кейсов, а в том, чтобы закреплённые ожидания показали, какие части клиента переносимы, а какие нужно держать локально.

Тест на ошибку - самый показательный, потому что здесь совместимость с OpenAI обманывает первой. По официальной справке ответ об ошибке у Z.AI - это плоский объект `{code, message}`, структурно отличный от вложенного `error` у OpenAI. Плюс проприетарная числовая таксономия кодов, привязанная к HTTP-статусам: 1000/1001/1003 - сбои аутентификации, 1211 - неизвестная модель, 1213 - отсутствует обязательный параметр, 1302 - превышен лимит запросов, 1305 - временная перегрузка. Контрактный тест должен целиться в эти коды явно, а не выводить их из привычек OpenAI. Если у тебя нет теста ошибки - у тебя нет контракта, есть только надежда.

    # GLM-клиент: перевод сырого ответа Z.AI в доменную ошибку def map\_error(status: int, body: dict) -> DomainError: code = body.get("code")          # плоский {code, message}, не error.\* message = body.get("message", "") if code in (1000, 1001, 1003): return AuthError(message)     # ключ/аутентификация if code == 1211: return BadModelError(message) # неизвестная модель if code == 1213: return BadRequestError(message) if code in (1302, 1305): return TemporaryError(message)  # лимит или перегрузка -> ретрай return DomainError(message)

Тест на обычный ответ фиксирует не «пришло 200», а форму полезной нагрузки. Здесь важна тонкость: поле `reasoning_content` документировано как поддерживаемое конкретно серией GLM-4.5. Значит, его присутствие в «нормальном ответе» - свойство модели, а не гарантия общего эндпоинта. Если доменный код рассчитывает на это поле всегда, он привязан к одной серии моделей, и эта привязка не видна из синтаксиса. Тест закрепляет: при модели X поле есть, при модели Y его может не быть, обработчик обязан пережить оба случая.

![Сравнительная таблица: вложенный объект error у OpenAI против плоского {code, message} и числовых кодов у Z.AI.](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/03-163.png)

## Где проходит граница адаптера?

Дальше решение, ради которого всё затевалось: что именно изолировать. Сразу оговорюсь - деление на «переносимое» и «локальное» Z.AI нигде не публикует, это моя классификация. Документация даёт поверхность, границу проводит инженер. Таблица ниже - гипотеза, которую контрактный тест на твоём сценарии подтвердит или опровергнет, а не универсальная истина.

Логика границы такая. В адаптер уходит всё, что можно выразить как общий контракт: выбор base URL по региону и плану, форма заголовка авторизации, перевод сырой ошибки в доменный тип. В GLM-клиенте остаётся всё, что несёт семантику конкретного поставщика и меняется по версиям: поля рассуждений, модельные умолчания, числовые коды. Домен не должен видеть ни `code: 1211`, ни `reasoning_content` - он видит `BadModelError` и «ответ готов».

| Элемент | Куда относится | Почему |
| --- | --- | --- |
| Выбор base URL (регион, Coding Plan) | Адаптер | конфигурация маршрута, не доменное правило |
| `z ai api key` в заголовке `Bearer` | Адаптер | форма аутентификации переносима |
| Перевод `{code, message}` в доменную ошибку | Адаптер | домен знает тип, не число |
| Поля `thinking` / `clear_thinking` | GLM-клиент | нет эквивалента в схеме OpenAI |
| `reasoning_effort` и его ремаппинг | GLM-клиент | семантика зависит от версии модели |
| Наличие `reasoning_content` | GLM-клиент | свойство серии GLM-4.5 |

У границы адаптера есть дешёвая проверка на прочность: если она проведена верно, к адаптеру подключается второй совместимый маршрут, а домен этого не замечает. [provod.ai](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a064-z-ai&utm_content=inline&utm_id=brief-a064) для такой проверки удобен тем, что говорит на SDK OpenAI и Anthropic: меняешь ключ и base\_url, код не переписываешь. Но ловушка ровно та же, что с GLM - совпадение по SDK не доказывает совпадение по поведению, поэтому второй маршрут гоняется через тот же контрактный набор независимо.

    # Тот же адаптер, другой совместимый маршрут - проверяется отдельными тестами client = OpenAI( api\_key=os.environ["PROVOD\_KEY"], base\_url="https://api.provod.ai/v1", ) # домен по-прежнему не знает имени поставщика

![Таблица-решение: переносимые элементы в адаптере против модельно-зависимых в GLM-клиенте.](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/04-161.png)

## Один параметр, разные смыслы: модельная конфигурация

Третий контрактный тест - на конфигурацию модели - вскрывает самое коварное. Даже одно и то же имя параметра не несёт одинаковой семантики по линейке GLM. По документации Z.AI `reasoning_effort` поддерживается только на GLM-5.2, причём с объявленным внутренним ремаппингом значений: `low`/`medium` превращаются в `high`, `none`/`minimal` выключают режим размышления, `xhigh` становится `max`. То есть ты передаёшь `low`, рассчитывая на экономный режим, а получаешь `high`. Это не баг, это документированное поведение, и оно не видно из синтаксиса запроса.

Дальше - умолчания. Поведение размышления по умолчанию различается по версии: GLM-5.2, GLM-5.1, GLM-5, GLM-5-Turbo, GLM-5V-Turbo, GLM-4.6 и GLM-4.5 сами решают, думать ли, тогда как GLM-4.7 и GLM-4.5V думают принудительно по умолчанию. Плюс GLM-специфичные поля запроса: объект `thinking` со значениями `type: "enabled" | "disabled"` и флаг `clear_thinking` (по умолчанию `true`), который отбрасывает `reasoning_content` предыдущего хода перед отправкой контекста модели. Ни `thinking`, ни `clear_thinking` не имеют эквивалента в стандартной схеме чат-комплишенов OpenAI. Всё это - конфигурационные расхождения, которые обязаны жить в GLM-клиенте и никогда не всплывать в домене.

Отсюда следует неприятное для планирования свойство: такой контракт живёт на версии и дате, а не «навсегда». В документации на 18 июля 2026 сосуществуют версии от GLM-4.5 до GLM-5.2, и именно версионно-зависимые умолчания меняются быстрее всего. Поэтому в тесте конфигурации имя модели стоит фиксировать явно - иначе при следующем обновлении линейки он останется зелёным, проверяя уже не то, что ты имел в виду.

![Схема ремаппинга reasoning_effort и разделение версий GLM по поведению размышления по умолчанию.](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/05-133.png)

## Как это применить у себя: шаги

1. Определи свой тип аккаунта и регион, затем зафиксируй ровно один base URL из трёх. Общий зарубежный, общий материковый (Zhipu/BigModel) или Coding Plan - это разные контракты, и ключ одного не работает против другого.
2. Заведи `z ai api key` в заголовок `Bearer` внутри адаптера, а не в доменном коде. Домен не должен уметь конструировать запрос руками.
3. Напиши тест ошибки первым. Замокай ответы с кодами 1000, 1211, 1213, 1302, 1305 и проверь, что каждый переводится в свой доменный тип из плоского `{code, message}`.
4. Напиши тест обычного ответа так, чтобы он проходил и при наличии `reasoning_content`, и без него. Привязка к серии GLM-4.5 не должна течь в домен.
5. Напиши тест конфигурации: передай `reasoning_effort: "low"` на GLM-5.2 и закрепи, что клиент осознаёт ремаппинг в `high`. Зафиксируй умолчание размышления для конкретной версии, которую ты используешь.
6. Прогони тот же набор против любого другого совместимого маршрута отдельно. Совпадение SDK - не совпадение поведения.

## Чего этот подход не решает

Контрактный адаптер не доказывает, что GLM ведёт себя как любой другой совместимый API. Он показывает только, где формы расходятся, - и то в тех местах, куда ты догадался прицелиться тестом. Пороги лимитов, retry-after и цены сюда не входят: коды 1302 и 1305 документированы как категории, а не как числа, и проверенных значений у меня нет.

Главное ограничение я уже назвал в начале, но повторю в конце: это метод к исполнению, а не отчёт о выполненном прогоне. Всё выше - документированная поверхность API на 18 июля 2026. Ценность метода проверяется на твоём сценарии, не на моём.

## FAQ

### Это один и тот же поставщик - Z.AI, Zhipu, GLM?

По официальной документации Z.AI - международный бренд, материковый маршрут ведёт на Zhipu/BigModel (`open.bigmodel.cn`), GLM - семейство моделей. За названиями `glm ai api` и `zhipu ai api` стоит та же вендор-поверхность, но контракт всё равно проверяется по своему эндпоинту.

### Какой base URL брать по умолчанию?

Умолчания нет. SDK требует явного выбора региона, а Coding Plan использует отдельные адреса. Поэтому выбор endpoint - решение, которое принимается до первого запроса, а не подбирается по ходу.

### Почему нельзя парсить ошибку как у OpenAI?

Потому что у Z.AI ошибка - плоский `{code, message}` с числовой таксономией, а не вложенный `error`. Тест ошибки ловит это первым.

### Есть ли бесплатный доступ?

Бесплатные лимиты и тарифы (`z ai api free`) в проверенные источники этого материала не входили, поэтому подтвердить их я не могу. Смотри актуальную документацию Z.AI на день интеграции.

Итоговое решение простое и проверяемое: планируй GLM-интеграцию через контрактный адаптер и не привязывай доменную логику к имени поставщика. Часть контракта считается переносимой только после того, как закреплённые ожидания совпали - до этого у тебя гипотеза, а не карта. Начальная работа над адаптером окупается тем, что будущая смена контракта локализуется в одном месте, а не расползается по продукту.

![provod.ai - один совместимый API к нескольким моделям с рублёвой оплатой из России.](https://storage.yandexcloud.net/provod-yc-production-cms-media/provod-yc-production-cms-media/blog/06-116.png)

## provod.ai — один API для привычных AI-инструментов

**Подключайте клиенты, агентов, IDE, SDK, библиотеки и приложения с поддержкой OpenAI-совместимого API:** во многих случаях достаточно заменить базовый URL и ключ без изменения прикладного кода.

**В одном каталоге — актуальные модели для текста и медиа:** GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.

**Широкая совместимость не оплачивается отдельной наценкой:** тарифы моделей остаются на уровне официальных провайдеров 1:1, а расчёты объединяются в рублёвом балансе.

**Подключите привычный инструмент к provod.ai:** [миграция OpenAI SDK](https://provod.ai/docs/migration) · [форма регистрации](https://app.provod.ai/register) · [цены на модели](https://app.provod.ai/models) · [защита данных по 152-ФЗ](https://provod.ai/legal/152-fz)

### Источники

- Z.AI Developer Documentation, Quick Start - `https://docs.z.ai/guides/overview/quick-start` (обращение 2026-07-18).
- Z.AI Developer Documentation, API Codes - `https://docs.z.ai/api-reference/api-code` (обращение 2026-07-18).
- Z.AI Developer Documentation, Chat Completion - `https://docs.z.ai/api-reference/llm/chat-completion` (обращение 2026-07-18).
- Z.AI Developer Documentation, Coding Plan Quick Start - `https://docs.z.ai/devpack/quick-start` (обращение 2026-07-18).
- Z.AI (zai-org) GitHub, z-ai-sdk-python - `https://github.com/zai-org/z-ai-sdk-python` (обращение 2026-07-18).

## FAQ

### Что такое provod.ai?

provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md).

### У provod.ai самые низкие цены среди российских провайдеров?

Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md).

### Можно ли обещать отсутствие наценки?

Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения.

### Насколько стабилен сервис?

provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора.

### Почему provod.ai подходит для юридически оформленной работы в России?

provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента.

### provod.ai работает без VPN?

Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге.

### Какие протоколы и интеграции доступны?

Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели.

### Есть изображения и видео?

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

### Какие источники считать актуальными?

Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).