Ключ Doubao API создаётся не в приложении Doubao, а в консоли Volcano Ark. Многие ищут не там: листают настройки чат-приложения или ищут вход в центре расходов. Запомните: Doubao — семейство моделей, Volcano Ark — платформа, предоставляющая эти модели, а ключ принадлежит определённому рабочему пространству аккаунта Volcano Engine.
Статья последовательно разбирает путь «открыть аккаунт — создать ключ — ограничить права — подтвердить модель — разобрать 401 — выполнить ротацию»; цены и квоты определяются консолью.
Примечание: Doubao, Volcano Ark, Volcano Engine и ByteDance — товарные знаки или названия продуктов ByteDance и связанных компаний. Статья носит технический характер; она не подразумевает аффилированности, агентских отношений или одобрения со стороны этих компаний. Интерфейсы, права и квоты могут меняться — сверяйтесь с официальной документацией и консолью.
1. Сначала разделите аккаунт, ключ, рабочее пространство и модель
Проблемы с ключом обычно возникают, когда четыре объекта ниже не согласованы:
| Объект | Где находится | Назначение | Частая ошибка |
|---|---|---|---|
| Аккаунт Volcano Engine | Регистрация, верификация, центр расходов | Определяет баланс, договор, счета и владельца ключа | Личный аккаунт для корпоративных задач: счета и оплата потом не сходятся |
| API Key | Страница управления API Key в консоли Ark | Удостоверение при вызове | Пробел или перевод строки при копировании, ключ во фронтенде |
| Рабочее пространство | Переключатель в левом нижнем углу консоли | Изолирует ресурсы, участников и права | Ключ и эндпоинт в разных пространствах — вызов отклонён |
| Модель или эндпоинт | Список моделей, страница онлайн-инференса | Определяет, какая модель вызывается | Путаница между ID модели и ID эндпоинта с префиксом ep- |
Мнемоника: аккаунт решает, кто платит; рабочее пространство — что видно; ключ — от чьего имени идёт вызов; модель или эндпоинт — какая версия вызывается. Любое рассогласование может проявиться как 401 или 404.
2. Откройте Volcano Ark и создайте API Key
На примере консоли Volcano Ark процесс выглядит так:
- Зарегистрируйте аккаунт Volcano Engine и пройдите верификацию. Для бизнеса используйте юридическое лицо, чтобы договор, платёж и счёт совпадали.
- Войдите в консоль Volcano Ark, убедитесь, что сервис активирован, и выберите регион, например Северный Китай (Пекин).
- В левом нижнем углу проверьте текущее рабочее пространство. Новый аккаунт обычно находится в пространстве по умолчанию; для командного проекта создайте отдельное.
- Откройте страницу управления API Key и нажмите «Создать API Key». В названии укажите назначение и среду, например
doubao-dev-202610,doubao-prod-202610. - Сразу сохраните ключ в менеджере паролей или серверном хранилище секретов. Не передавайте полный ключ через мессенджеры или почту.
- Создавайте отдельные ключи для теста, предпродакшена и продакшена. Текущая документация указывает, что основной аккаунт по умолчанию может создать до 50 API Key.
Одна деталь: официальная документация сообщает, что с 17 сентября 2026 года новые ключи используют новый открытый формат, а способ аутентификации не меняется; ранее созданные ключи продолжают работать. Оба варианта внешне нормальны — сначала проверьте, к какому рабочему пространству относится ключ.
3. Границы прав ключа: пространство, белый список моделей и IP
API Key — не универсальный ключ ко всему аккаунту. Документация прямо указывает: ключ даёт доступ только к моделям и приложениям того рабочего пространства, где он создан, и не работает между проектами; после переноса эндпоинта в другое пространство старый ключ перестаёт действовать.
При создании или после него обычно доступны два способа ужесточить права:
- ограничить модели: разрешить ключу вызывать только указанные ID моделей или пользовательские эндпоинты, чтобы один ключ не открывал все модели;
- ограничить IP-источник: настроить белый список IP и снизить риск использования украденного ключа из другого места.
В командной работе делите ключи по «приложению + среде», а не по сотрудникам. При увольнении отключайте только связанные ключи, не затрагивая другие сервисы; храните журналы вызовов, чтобы видеть, какой ключ когда и какую модель вызывал. Рабочие пространства подходят для изоляции проектов; права участников и квоты определяются консолью.
4. ID модели и ID эндпоинта: не смешивайте
В Volcano Ark есть два распространённых способа вызова:
- предустановленный инференс: создавать эндпоинт заранее не нужно, в
modelуказывается ID модели, напримерdoubao-seed-2-1-pro-260915. ID обычно содержит дату версии, суффикс нельзя опускать по памяти; - пользовательский эндпоинт: создаётся на странице «Онлайн-инференс», в
modelуказывается ID эндпоинта (обычно начинается сep-). Подходит для фиксированного развёртывания, тонкого управления или моделей с LoRA. Эндпоинт должен перейти из состояния «в планировании» в «здоров», иначе стабильный вызов невозможен.
Разница не только в формате. Документация указывает: при подписи Access Key (AK/SK) в поле model обязательно указывается ID эндпоинта; при использовании API Key по документации можно указать ID модели или эндпоинта. Для части моделей или аккаунтов прямой вызов по ID модели не открыт — при указании имени модели возвращается InvalidEndpointOrModel.ModelIDAccessDisabled; тогда нужно создать пользовательский эндпоинт и использовать ep- ID.
Поэтому при создании ключа привязывать модель не обязательно, но перед запуском подтвердите: модель доступна в текущем аккаунте и регионе, ключ имеет к ней доступ, а model в запросе соответствует способу вызова. Сопоставление названий — по консоли и странице цены на модели.
5. Поместите ключ в переменные окружения
Не встраивайте ключ в код, конфигурационные файлы или собранный фронтенд. На сервере обычно используют переменные окружения:
# .env хранится только локально или в сервисе секретов и добавлен в .gitignore
export ARK_API_KEY="ваш API Key Volcano Ark"
export ARK_MODEL_ID="doubao-seed-2-1-pro-260915"
# при использовании пользовательского эндпоинта:
# export ARK_ENDPOINT_ID="ep-ваш-ID-эндпоинта"
В Python читайте через os.environ["ARK_API_KEY"] без значения по умолчанию. В контейнерах монтируйте Secret, в CI/CD используйте зашифрованные переменные; в журналах фиксируйте только префикс или отпечаток ключа. Браузер, мобильное приложение и мини-программа не должны хранить ключ напрямую — все запросы идут через серверный прокси.
6. Как разбирать 401, 403, 404 и 429
| Симптом | Частый код ошибки | Частая причина | Действие |
|---|---|---|---|
| 401 | AuthenticationError |
Ключ отсутствует, неверен, отключён или в заголовке нет Bearer |
Скопируйте ключ заново, проверьте заголовок Authorization, убедитесь, что ключ и эндпоинт в одном пространстве |
| 403 | AccessDenied |
Ключу запрещены модель или IP, у аккаунта нет прав на ресурс | Проверьте белый список ключа, IP и права пространства |
| 404 | InvalidEndpointOrModel.NotFound |
Неверный ID модели или эндпоинта либо ресурса нет в пространстве | Скопируйте полный ID из консоли, сверьте регион и пространство |
| 404 | ModelNotOpen |
Модель не активирована в аккаунте | Активируйте модель в консоли Ark |
| 404 | InvalidEndpointOrModel.ModelIDAccessDisabled |
Аккаунту запрещён прямой вызов по ID модели | Создайте пользовательский эндпоинт и используйте ep- ID |
| 429 | RateLimitExceeded.* |
Превышены RPM/TPM аккаунта, модели или эндпоинта | Снизьте параллелизм, повторите с экспоненциальной задержкой, при необходимости запросите повышение квоты |
| 500/503 | InternalServiceError, ServerOverloaded |
Сбой или перегрузка upstream | Подождите и повторите, подготовьте резервную модель или канал |
Порядок разбора: сначала HTTP-статус, затем код ошибки, затем тело запроса. При 401 не спешите винить баланс; недостаток средств обычно соответствует 403 AccountOverdueError. При 404 не меняйте код — сначала заново скопируйте ID модели и эндпоинта из консоли.
7. Прямое подключение или единый шлюз
Прямое официальное подключение подходит командам, которые используют только Doubao, самостоятельно проходят верификацию и пополняют баланс, а также нуждаются в договоре и счетах Volcano Engine. Ключ и Base URL должны использоваться парой: официальный ключ — только с https://ark.cn-beijing.volces.com/api/v3, ключ шлюза — только с адресом шлюза; смешивание обычно сразу даёт 401.
Единый шлюз подходит, если одновременно используются Doubao, DeepSeek и другие модели либо нужен один вход для общих счетов, квот и журналов. При выборе шлюза уточните: как сопоставляются названия моделей, полностью ли поддержаны стриминг и вызов инструментов, можно ли ограничивать ключи по проектам, как уведомляют о сбоях, соответствуют ли условия обработки данных требованиям. ZSQH AI Gateway — независимый сторонний сервис подключения, не связанный с ByteDance; для теста создайте аккаунт на странице регистрации, биллинг смотрите на странице цены на модели.
8. Ротация и обработка утечки
У ключа должен быть жизненный цикл, как у пароля, а не работа «до первой ошибки»:
- Создайте новый ключ с теми же правами и сначала дайте его только тестовым или канареечным экземплярам.
- Обновите переменные окружения или хранилище секретов, перезапустите сервис и убедитесь, что вызовы проходят.
- Наблюдайте 24–72 часа за долей ошибок, задержкой и расходом. После стабилизации отключите старый ключ, но не удаляйте сразу — сохраните его на время для отката.
- При смене персонала, утечке кода или появлении ключа в публичном репозитории немедленно отключите и создайте новый ключ, а не просто меняйте пароль.
- Проверьте детализацию расхода и журналы на аномальные модели, часы и IP-источники.
Документация также напоминает: утечка ключа означает, что другие могут расходовать вашу квоту. При обнаружении сначала отключите ключ, чтобы остановить потери, затем выясняйте причину.
Похожие материалы:
Часто задаваемые вопросы
Можно ли создать ключ Doubao API в приложении Doubao?
Нет. Приложение Doubao предназначено для обычных пользователей, а API Key создаётся на странице управления API Key в консоли Volcano Ark.
Нужно ли выбирать модель при создании ключа?
Обычно нет. Ключ — учётные данные аккаунта или рабочего пространства, конкретная модель указывается в поле model запроса; при желании можно ограничить ключ доступными моделями или эндпоинтами.
Почему ключ работал вчера, а сегодня возвращает 401?
Частые причины: ключ отключён или ротирован, ключ и эндпоинт в разных пространствах, эндпоинт перенесён, в заголовке нет Bearer, статус аккаунта ненормален. Сначала проверьте принадлежность ключа, затем заголовок и рабочее пространство.
Что указывать: ID модели или ID эндпоинта с ep-?
Для предустановленного инференса — ID модели; для пользовательского эндпоинта — ep- ID; при подписи Access Key обязательно ID эндпоинта. Если возвращается ModelIDAccessDisabled, прямой вызов по ID модели недоступен — создайте эндпоинт.
Что делать в первую очередь при утечке ключа?
Немедленно отключите или удалите скомпрометированный ключ, создайте замену и обновите серверную конфигурацию, затем проверьте расход и журналы. Не начинайте с расследования пути утечки, иначе квоту продолжат расходовать.
