Гайды

Qwen API: как получить ключ и сделать первый запрос

8 октября 2026 · 17 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 8 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

Qwen API — это доступ к моделям Qwen через облако Alibaba Cloud Model Studio. Чтобы сделать первый запрос, нужно активировать сервис, создать API-ключ, узнать Workspace ID, собрать Base URL вида https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1 и отправить запрос к модели qwen3.8-max. Ниже — пошаговый разбор по официальной документации Alibaba Cloud.

Что такое Qwen API и где он живёт

Qwen API — это программный интерфейс к моделям Qwen на платформе Alibaba Cloud Model Studio. По документации Alibaba Cloud, Model Studio поддерживает вызовы моделей через OpenAI-совместимые интерфейсы и через DashScope SDK. Это значит, что код, написанный под OpenAI SDK, переносится на Model Studio заменой трёх вещей: API-ключа, Base URL и имени модели.

Ключевое для читателя: Qwen API — облачный сервис. Вызов направляется в облачный контур Alibaba Cloud. Если нужен локальный запуск моделей, это другая задача — про неё есть отдельный материал про Ollama и про LM Studio.

По нашему прогону выдачи: скачали топ-10 выдачи DuckDuckGo (ru-RU) по запросу «qwen api»: текст отдали 6 из 10. Медиана объёма читаемого текста топа — 2970 слов. Метку 2026 года несут 3 из 6 прочитанных страниц.

Активация сервиса и проверка консоли

Первый шаг — аккаунт и активация. По документации Alibaba Cloud, порядок такой: создать аккаунт Alibaba Cloud, зайти в Model Studio, прочитать и принять условия обслуживания. Если диалог с условиями не появился, сервис уже активирован.

После активации откройте консоль и проверьте раздел биллинга. Это важно до первого запроса: вы должны видеть, что аккаунт активен и что способ оплаты настроен. Документация не обещает бесплатной квоты автоматически — наличие free quota зависит от аккаунта и региона, и в консоли это отображается отдельно. Если консоль показывает бесплатную квоту, она есть; если не показывает — не рассчитывайте на неё.

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

Получение API-ключа

По документации Alibaba Cloud, ключ создаётся на странице API Key в консоли Model Studio. Порядок:

1. Выберите регион в правом верхнем углу.
2. Нажмите Create API Key.
3. В диалоге выберите Workspace (рекомендуется default workspace), при желании добавьте описание.
4. В разделе Permissions выберите All либо Custom для тонкой настройки.
5. Нажмите OK.

Полный ключ и API Host показываются один раз, в диалоге после создания. Их нужно сразу скопировать или скачать. После закрытия диалога plaintext-ключ больше не отображается. Если ключ потерян — его сбрасывают или создают новый.

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

Workspace ID и Base URL

Workspace ID нужен для регионов China (Beijing), Singapore, Japan (Tokyo), Germany (Frankfurt) и China (Hong Kong). Его находят на странице Workspace Management в консоли. Для региона US (Virginia) workspace-домены не поддерживаются, и Workspace ID в Base URL не включается.

Для Сингапура Base URL такой:

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

Замените {WorkspaceId} на фактический ID из Workspace Management. Для HTTP-запроса полный endpoint — тот же адрес плюс /chat/completions.

По документации, для Сингапура, Пекина и Гонконга введены workspace-домены; старые домены вроде dashscope-intl.aliyuncs.com ещё доступны, но рекомендуется переходить на новые.

Переменная окружения для ключа

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

echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
source ~/.bashrc

Для macOS с Zsh — аналогично, но в ~/.zshrc. Для Windows через PowerShell:

[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

Проверка наличия переменной в Python без вывода самого ключа:

import os
print(bool(os.getenv('DASHSCOPE_API_KEY')))

Этот код печатает True или False и не раскрывает значение ключа. Не выводите сам ключ в логи и не коммитьте его в репозиторий.

Первый запрос: минимальный Python-клиент

Ниже — минимальный клиент на OpenAI SDK. Он использует переменную окружения и возвращает текст из choices[0].message.content.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

print(completion.choices[0].message.content)

Замените {WorkspaceId} на фактический ID. Модель qwen3.8-max — пример из документации; список поддерживаемых моделей смотрите в Model list.

Тот же запрос через curl по официальному API:

curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.8-max",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"}
    ]
}'

Ответ приходит в формате OpenAI: объект choices, внутри — message с полем content. В блоке usage указаны prompt_tokens, completion_tokens и total_tokens. Конкретные значения зависят от запроса; в документации приведены примеры, но ваши числа будут другими.

Что делать при ошибке 401

Ошибка 401 с сообщением Incorrect API key provided и кодом invalid_api_key в том числе означает несовпадение региона. По документации, API-ключ привязан к региону создания: при вызове endpoint другого региона запрос отклоняется с ошибкой аутентификации. Сам по себе код 401 не позволяет отличить неверный ключ от несоответствия региона: проверяйте ключ и endpoint вместе.

Порядок действий:

1. Прочитайте первичный ответ об ошибке — в нём указаны code и message.
2. Сверьте регион ключа и регион Base URL.
3. Создайте ключ в консоли того региона, чей endpoint вызываете.
4. Повторите запрос один раз с исправленными данными.

Не запускайте платные повторы ради проверки гипотез. Сначала устраните причину по тексту ошибки.

Рабочий процесс: от ключа до ответа

Соберём последовательность, которая снижает число неудачных попыток:

1. Активируйте Model Studio и примите условия.
2. Проверьте биллинг и регион в консоли.
3. Создайте API-ключ и сразу сохраните его.
4. Найдите Workspace ID на странице Workspace Management.
5. Соберите Base URL для нужного региона.
6. Положите ключ в переменную окружения.
7. Отправьте один запрос к qwen3.8-max.
8. Прочитайте ответ: choices[0].message.content при успехе, code и message при ошибке.

Этот порядок — авторская формулировка, основанная на структуре официальной документации. Он не заменяет документацию, но помогает не пропустить шаг.

Локальная проверка проекта перед запросом

До сетевого запроса проверьте локальную конфигурацию: интерпретатор, импорт SDK, наличие переменной окружения и заполнение адреса. Эти проверки не устанавливают частоту причин отказов сервиса. Ниже учебный проект и порядок проверки; платный запрос редакция не выполняла.

Создайте отдельную папку, например qwen-first-call, и работайте только внутри неё. Это важно: чем меньше посторонних файлов рядом, тем меньше шансов, что Python подхватит не тот модуль. Внутри папки будет ровно один файл с кодом — hello_qwen.py. Имя выбрано намеренно нейтральным. Файл openai.py в рабочей папке — классическая ловушка: Python ищет модули сначала в текущем каталоге, и такой файл затеняет установленный пакет openai. Импорт при этом не падает с внятной ошибкой, а ведёт себя странно: атрибуты отсутствуют, классы не те. Если вы когда-нибудь называли файл так же, как библиотеку, переименуйте его до запуска.

Установка пакета выполняется командой:

python -m pip install openai

Запись через python -m pip привязывает установку к тому же интерпретатору, который потом запустит скрипт. Команда pip install openai без префикса иногда попадает в другой Python — системный, из другой виртуальной среды, из другого менеджера версий. Внешне всё выглядит установленным, а при запуске появляется ModuleNotFoundError: No module named 'openai'. Если вы работаете в виртуальной среде, активируйте её до установки и до запуска, чтобы установка и запуск шли через один и тот же python.

Сохраните клиент в hello_qwen.py. Ключ берётся из переменной окружения. Если реальный ключ попал в опубликованный код или переданный файл, отзовите его и создайте новый. Наличие строки в частном локальном файле само по себе не доказывает утечку.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

print(completion.choices[0].message.content)

Замените {WorkspaceId} на фактический идентификатор из консоли. Запуск:

python hello_qwen.py

Перед этим стоит пройти четыре локальные стадии. Они условные и удостоверяемые: на каждой вы проверяете наблюдаемый результат.

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

import os
import sys

print("interpreter:", sys.executable)
print("key present:", bool(os.getenv("DASHSCOPE_API_KEY")))

Первая строка показывает полный путь к Python. Сравните его с тем, куда вы ставили пакет. Вторая строка печатает True или False. Значение ключа не выводится — только факт наличия. Если False, переменная не попала в окружение этого процесса. Частая причина: переменную добавили в конфигурационный файл оболочки, но не перезапустили терминал, либо запускают скрипт из другого окна, где окружение ещё старое. Ещё одна причина: переменную задали в одном терминале, а запуск делают из IDE, у которой своё окружение.

Стадия импорта. Убедитесь, что импортируется установленный пакет. Проверьте, нет ли одноимённого файла в папке проекта. Проверка — путь к модулю:

import openai
print("openai from:", openai.__file__)

Проверьте, что openai.file указывает на установленный пакет. Если импортируется одноимённый файл проекта, переименуйте его, перезапустите процесс и повторите проверку пути.

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

Стадия сети. Только после первых трёх стадий имеет смысл делать вызов. Один запрос, один ответ, без повторов. Если ответ не пришёл, сначала изучите текст ошибки.

Соберите эти стадии в короткую последовательность: окружение → импорт → конфигурация → сеть → разбор ответа. Такой порядок отделяет локальные причины от удалённых. Ниже — таблица для быстрой диагностики.

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

Как отделить ошибку Python от ответа сервиса

Когда скрипт не печатает ожидаемый текст, полезно сразу понять, на каком уровне произошёл сбой. Ошибка Python и ответ сервиса выглядят по-разному, и лечатся они в разных местах.

Трассировка Python сама по себе не показывает, был ли сетевой запрос. Посмотрите тип исключения и место сбоя: ошибка импорта указывает на загрузку пакета, ошибка обращения к полю может возникнуть после ответа. Сетевые ошибки SDK и ошибки API тоже могут приходить как исключения Python.

Ответ сервиса приходит как результат вызова. Успешный ответ — это объект с полем choices, внутри которого лежит message, а в нём content. Именно content содержит текст. Если вы печатаете объект целиком, вы видите служебную структуру с ответом модели внутри. Если вы обращаетесь к content у неверного уровня, получаете AttributeError уже после успешного сетевого вызова — и это сбивает с толку, потому что сеть-то работала.

Неуспешный ответ сервиса обычно приходит как исключение с кодом и сообщением. Код указывает на класс проблемы, сообщение — на детали. Читайте их вместе. Один и тот же код в разных ситуациях означает разное, поэтому не стоит запоминать «код = причина» без текста.

Практический приём: оберните вызов так, чтобы отделить локальную ошибку от ответа сервиса, не раскрывая секрет в выводе.

import os
from openai import OpenAI

key = os.getenv("DASHSCOPE_API_KEY")
if not key:
    raise SystemExit("Переменная окружения с ключом не найдена")

client = OpenAI(
    api_key=key,
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

try:
    completion = client.chat.completions.create(
        model="qwen3.8-max",
        messages=[{"role": "user", "content": "Who are you?"}],
    )
except Exception as exc:
    print("тип:", type(exc).__name__)
    print("Сверьте локально код ответа и текст ошибки; скройте ключ при сохранении лога")
else:
    print(completion.choices[0].message.content)

Здесь отсутствие ключа проверяется до создания клиента. Исключение из вызова попадает в except, который печатает только имя типа; текст исключения этот пример не выводит. Если вызов завершился без исключения, else пытается прочитать текст ответа. Ошибки чтения в else потребуют отдельной проверки структуры.

Else выполняется, если блок try завершился без исключения. Это разделяет обработку сбоя вызова и чтение результата, но не гарантирует, что любое последующее обращение к полям будет успешным.

Ещё одна привычка, которая экономит время: не эмулируйте платный вызов ради проверки гипотез. Если нужно убедиться, что клиент собран правильно, проверяйте параметры клиента локально, без отправки запроса. Если нужно понять формат ответа, сначала прочтите описание формата в документации. Каждый реальный вызов — это обращение к сервису, и его лучше делать тогда, когда локальные стадии уже пройдены.

Разбор ответа тоже стоит держать явным. Текст лежит в choices[0].message.content. Если структура неожиданная, сначала посмотрите, какие поля вообще есть в объекте, и только потом обращайтесь к вложенным. Так вы не спутаете отсутствие поля с ошибкой сети.

Наконец, держите один рабочий пример и один способ запуска. Когда в папке лежит несколько похожих скриптов, легко запустить не тот файл и искать причину там, где её нет. Один файл, одна команда запуска, один порядок стадий — и любое отклонение от ожидаемого результата сразу указывает на конкретный уровень.

Учебная проверка чтения JSON без обращения к API

Перед сетевым вызовом можно отдельно проверить чтение результата на собственном учебном словаре Python. В этом примере нет ключа, адреса сервиса и вызова клиента. Словарь создан редакцией для проверки локального кода; он не является сохранённым ответом Qwen. Такой тест помогает увидеть, как ваш обработчик ведёт себя при отсутствующем списке вариантов или пустом содержимом сообщения.

fixture = {"choices": [{"message": {"content": "Учебный ответ"}}]}

choices = fixture.get("choices") or []
if choices:
    message = choices[0].get("message") or {}
    content = message.get("content")
    if isinstance(content, str):
        print(content)
    else:
        print("Проверьте содержимое учебного сообщения")
else:
    print("В учебном словаре нет вариантов ответа")

Редакция выполнила отдельную локальную проверку на учебных словарях: строковое содержимое извлекается, пустой список, словарь ошибки и значение None не принимаются за текст ответа. Сетевые запросы в этой проверке отсутствовали. Это проверка обработчика данных; она не подтверждает работу аккаунта, права ключа, баланс или доступность облачной модели.

Для собственной проверки замените строку учебного ответа короткой фразой и запустите файл. Затем временно замените список choices пустым списком: должен выполниться соответствующий локальный переход. Верните исходный учебный словарь, прежде чем переносить обработчик в клиент. При работе с настоящим ответом сначала прочитайте структуру, полученную от сервиса. Если она содержит ошибку, сохраните диагностические признаки отдельно от текста модели, предварительно исключив секреты. Учебный пример не устанавливает причину конкретного ответа сервера.

Частые вопросы

Как получить Qwen API key?

Ключ создаётся в консоли Alibaba Cloud Model Studio на странице API Key. Выберите регион, нажмите Create API Key, укажите Workspace и права, затем нажмите OK. Полный ключ показывается один раз — сразу скопируйте или скачайте его. После закрытия диалога plaintext-ключ не отображается.

Почему запрос возвращает 401 Incorrect API key provided?

По документации, одна из возможных причин — неверный ключ или несоответствие региона ключа и endpoint. API-ключ привязан к региону создания и не работает с endpoint другого региона. Создайте ключ в консоли того региона, чей Base URL вы вызываете, и повторите запрос.

Где взять Workspace ID для Base URL?

Workspace ID находится на странице Workspace Management в консоли Model Studio. Он нужен для регионов China (Beijing), Singapore, Japan (Tokyo), Germany (Frankfurt) и China (Hong Kong). Для US (Virginia) workspace-домены не поддерживаются, и Workspace ID в Base URL не включается.

Есть ли бесплатная квота у Qwen API?

Документация не обещает бесплатную квоту автоматически. Наличие free quota зависит от аккаунта и региона и отображается в консоли. Если консоль показывает квоту — она доступна; если не показывает, рассчитывать на неё не стоит. Проверяйте раздел биллинга до первого запроса.

Можно ли использовать OpenAI SDK с Qwen API?

Да. По документации, Model Studio поддерживает OpenAI-совместимые интерфейсы. Нужно заменить API-ключ, Base URL и имя модели. Код на OpenAI SDK переносится почти без изменений. Ответ приходит в формате OpenAI: объект choices с полем message.content.

Что дальше

Первый запрос — это проверка связки: ключ, регион, Base URL, модель. Когда она работает, дальше можно изучать расширенные возможности Qwen API по документации: потоковый вывод, структурированный вывод, вызов функций. Документация описывает их в разделе про генерацию текста.

Если вы работаете с другими AI-сервисами и сталкиваетесь с проблемами доступа, полезны материалы про оплату Z AI из России и про то, что делать, если Copilot не работает.