Как подключить Qwen4-Max API и перейти с preview на выпущенную модель
Выберите правильный ID Qwen4-Max, регион и способ оплаты. Проверьте лимиты вывода, историю инструментов и первый ответ перед переносом агента.
Qwen4-Max теперь описана в документации как выпущенная модель с API-идентификатором qwen4-max. Это не qwen4-max-preview. Если старая статья утверждает, что Qwen4 доступна только по подписке в режиме предварительного доступа, перед настройкой приложения проверьте актуальную официальную документацию.
Руководство проверено 16 ноября 2026 года. Здесь используется прямой API QwenCloud, разобраны решения при миграции и приведён небольшой валидатор ответа. Мы проверили документацию и локальные синтетические ответы; платных вызовов Qwen4 и измерений производительности для этой статьи не было. Примеры ниже — запросы для самостоятельного запуска и критерии приёмки, а не измеренные результаты модели.
Что изменилось и какую модель выбрать
Официальная страница модели теперь описывает qwen4-max, тогда как материалы предварительного доступа относятся к другому идентификатору. Используйте точное имя, доступное на выбранном маршруте. Не переносите префикс провайдера из другого шлюза и не принимайте подпись в клиенте за API ID.
Для выпущенной модели документированы генерация текста, понимание изображений и видео, вызовы инструментов и структурированный вывод. Для офисных сценариев важно различать возможности: понимание изображения не означает генерацию изображения, а текст для слайдов сам по себе не создаёт редактируемую презентацию. Создание, выполнение и передача файлов требуют соответствующих инструментов и управляющей среды, которая проверяет их результат.
| Решение | Что проверить перед изменением настроек |
|---|---|
| Выпущенная модель или preview | Для этого руководства выберите qwen4-max; настройку preview храните отдельно |
| Прямой API или шлюз | Проверьте каталог, ключи и протоколы именно выбранного провайдера |
| Оплата по использованию или Token Plan | Используйте endpoint и ключ, соответствующие этому способу оплаты |
| Регион | Согласуйте регион консоли, ключа и endpoint |
| Миграция агента | Проверьте выполненную задачу и её файлы, а не только успешный HTTP-ответ |
Официальный размер контекста — 1 000 000 токенов. Для выпущенной модели указано до 131 072 выходных токенов без рассуждений или до 262 144 токенов рассуждений и ответа вместе. Это предельные значения, а не рекомендуемые настройки первого запроса. Не переносите старый лимит preview в конфигурацию выпущенной модели.
Подключите прямой аккаунт QwenCloud
Для оплаты по использованию создайте или выберите API-ключ в нужном регионе QwenCloud. Следуйте официальной инструкции по ключам и справочнику регионов и endpoint. Перед запросом проверьте доступ аккаунта и оплату.
В этом примере используется Сингапур:
Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions
Для ключа Token Plan предусмотрен отдельный маршрут. Следуйте документации Token Plan, а не вставляйте этот ключ в пример оплаты по использованию. Совместимый протокол не объединяет права доступа и расчёт расходов двух маршрутов.
Храните ключ в серверной переменной окружения DASHSCOPE_API_KEY. Не добавляйте его в коммиты и скриншоты. Проверить наличие значения, не выводя его, можно так:
python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'
Эта проверка устанавливает только наличие значения. Принял ли выбранный маршрут ключ, покажет успешный аутентифицированный запрос.
Отправьте небольшой запрос и проверьте ответ
Сохраните следующий код в request.json:
{
"model": "qwen4-max",
"messages": [
{
"role": "user",
"content": "Return exactly three short checklist items for reviewing an API integration."
}
],
"enable_thinking": false,
"max_completion_tokens": 1024
}
Для узкой проверки соединения рассуждения явно отключены; это не рекомендация для всех задач программирования или исследований. Отдельные настройки описаны в руководстве по рассуждениям. Лимит токенов ограничивает вывод, но не весь возможный расход длинного процесса с инструментами.
Запускайте команду только после выбора нужного оплачиваемого аккаунта:
curl --silent --show-error --fail-with-body \
--max-time 120 \
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json \
-o response.json
Не повторяйте её автоматически после тайм-аута: сервер мог обработать запрос, даже если ответ не дошёл до терминала. Сначала проверьте журналы запросов и использования у провайдера. В примере намеренно нет автоматического цикла повторов.
Сохраните следующий код как check_response.py и выполните python3 check_response.py response.json:
import json
import sys
from pathlib import Path
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
raise SystemExit("API error: inspect response.json locally.")
choices = payload.get("choices") or []
if not choices:
raise SystemExit("No choices returned; inspect the response format.")
choice = choices[0]
reason = choice.get("finish_reason")
message = choice.get("message") or {}
text = message.get("content")
if reason != "stop":
raise SystemExit(f"Incomplete text check: finish_reason={reason!r}")
if not isinstance(text, str) or not text.strip():
raise SystemExit("No usable final text returned.")
print(text)
print("Usage:", payload.get("usage", "not supplied"))
Успешная проверка означает, что ответ содержит непустой текст и обычный маркер завершения. Нужно отдельно проверить, что в нём ровно три запрошенных пункта. Скрипт специально рассчитан на первый текстовый запрос: корректный вызов инструмента является другим, промежуточным результатом и не должен считаться готовым ответом.
Для воспроизводимости записывайте дату запроса, регион endpoint, возвращённый идентификатор модели, причину завершения, расход и результат задачи. Не публикуйте сырые ответы, если они содержат данные пользователей.
Перенесите существующего агента для кода или офисных задач
При миграции нужно ответить на два вопроса: выполняет ли новый маршрут нужный протокол и способен ли агент по-прежнему выдавать результат работы? Короткое приветствие не проверяет полностью ни протокол, ни качество.
- Сохраните текущие настройки. Запишите провайдера, модель, endpoint, версию клиента и права инструментов. Сделайте обратимое изменение вместо замены рабочего подключения сразу во всех средах.
- Начните с изолированной задачи. Возьмите небольшой репозиторий или синтетические офисные документы. Заранее определите ожидаемый результат: патч с проходящими тестами, книгу со сходящимися итогами или отчёт с проверяемыми ссылками.
- Проверьте настройки конкретного клиента. QwenCloud публикует отдельные инструкции для Qwen Code, Codex и Claude Code. Конфигурация одной управляющей среды не является универсальным примером API.
- Проверьте полный цикл инструмента. Попросите агента прочитать безопасный тестовый файл, вызвать инструмент только для чтения, получить результат и использовать его в ответе. Убедитесь, что ID вызова и история сохраняются на всём пути.
- Проверьте сам результат. Откройте созданный файл или просмотрите патч. Проверьте формулы, источники или тесты независимо от сообщения модели о завершении.
- Увеличивайте объём постепенно. На одинаковых входных данных сравните стоимость успешной задачи, время и вмешательства с текущей настройкой. Одного удачного ответа недостаточно для замены рабочего процесса.
Повторно используемый проверочный запрос для синтетической таблицы:
Use only the supplied sales.csv. Calculate revenue by month from quantity
and unit_price. Flag missing values rather than inventing them. Deliver:
1. the calculation method;
2. the totals with the source row IDs;
3. a list of excluded rows and reasons.
Do not claim to have created an Excel file unless you actually create and
attach one. Stop and report any tool or file-access failure.
Это предлагаемый тест, а не утверждение, что Qwen4 его прошла. Пересчитайте суммы самостоятельно, затем добавьте более сложные случаи — дубликаты строк и разные валюты.
Две детали миграции, которые могут незаметно испортить результат
Изменился бюджет вывода. В уведомлении о совместимости API сказано, что начиная с поколения Qwen4 preview параметр max_tokens ограничивает рассуждения и ответ вместе. Настройка, прежде оставлявшая достаточно места для видимого текста, может вести себя иначе при включённых рассуждениях. Прежде чем повышать лимит, проверьте статус завершения и расход. Меняйте по одному параметру и измеряйте стоимость.
Для истории инструментов недостаточно видимого ответа. Справочник вызовов инструментов и документация рассуждений объясняют перенос сообщений ассистента и результатов инструментов между ходами. Не восстанавливайте историю из обычного текстового транскрипта с потерей полей протокола. Общий подход есть в руководстве по многошаговым вызовам инструментов Qwen и других моделей; примеры для старых моделей не заменяют актуальный контракт Qwen4.
Найдите причину ошибки до повтора
| Симптом | Первая проверка | Следующий шаг |
|---|---|---|
| Ошибка аутентификации | Ключ соответствует маршруту и региону | Исправьте пару ключ/endpoint; не публикуйте секреты в обращении |
| Модель недоступна или не найдена | Точный ID, права аккаунта, каталог провайдера | Убедитесь, что маршрут предлагает qwen4-max; не угадывайте псевдонимы |
| Параметр запроса отклонён | Клиент отправляет настройки другой модели или протокола | Вернитесь к минимальному запросу выше и добавляйте нужные поля по одному |
| Обрезанный или пустой итоговый ответ | Причина завершения, бюджет рассуждений, лимит вывода | Изучите расход и исходный ответ до изменения бюджета |
| Цикл инструментов остановился | Вызов ассистента, соответствующий результат, история рассуждений | Сравните сериализованные сообщения с официальным многошаговым примером |
| Ограничение частоты | Квота аккаунта, параллелизм, рекомендации в ответе | Уменьшите параллелизм; где повтор допустим, применяйте ограниченные повторы с задержкой |
| Модель пишет «готово», но файла нет | Выполнение инструментов и сохранение артефактов | Потребуйте файл и проверьте содержимое до приёмки |
Это направления диагностики, а не перечень ошибок, воспроизведённых нами на Qwen4. Отличить неверный ID от неподдерживаемого endpoint поможет руководство по model not found (на английском).
Проверяйте стоимость и наличие в Ofox отдельно
Актуальный справочник цен QwenCloud различает регионы, вход, выход и операции кэширования. Токены рассуждений учитываются в стоимости вывода. Акция с кредитами preview не является универсальной ценой выпущенной модели, а квота Token Plan — ставкой оплаты по использованию.
Для сравнения без кэширования умножьте входные токены на применимую входную ставку и прибавьте выходные токены, умноженные на выходную ставку; обе ставки приведите к одинаковой единице токенов. Суммируйте все вызовы модели в цикле инструментов. Для кэшированных запросов учитывайте запись и чтение по правилам провайдера, не считая одни токены дважды. Рядом с результатом запишите регион и дату тарифов.
В снимке публичного каталога Ofox от 16 ноября Qwen4-Max не было. Поэтому приведённая настройка прямого QwenCloud не является инструкцией подключения через Ofox. Если нужен уже существующий маршрут Ofox, изучите страницу Qwen3.8 Max 0902 и оценивайте её как другую модель, а не псевдоним Qwen4.
Для запросов Ofox используйте аутентификацию API-ключом Ofox и обработку ошибок Ofox. Эти ключи и правила не аутентифицируют запрос к QwenCloud. До переноса настроек на шлюз подтвердите фактическую запись новой модели в каталоге и поддерживаемый протокол.
Часто задаваемые вопросы
- Qwen4-Max всё ещё доступна только в preview?
- Нет. Актуальная официальная документация указывает qwen4-max с оплатой по использованию и доступом через Token Plan. qwen4-max-preview — отдельный идентификатор; его условия нельзя переносить на выпущенную модель.
- Можно ли вызвать Qwen4-Max через Ofox?
- В публичном каталоге, проверенном 16 ноября 2026 года, Qwen4-Max не найдена. Руководство использует прямой QwenCloud и не утверждает доступность в Ofox.
- Контекст в миллион токенов означает миллион выходных токенов?
- Нет. Для выпущенной модели указан контекст 1 000 000 токенов и отдельные ограничения входа и вывода. Максимум вывода — 131 072 без рассуждений либо 262 144 токена рассуждений и ответа вместе.


