Seedance — видеомодель компании ByteDance. При работе с её API первый барьер — не промпт, а рабочий API Key, который нужно правильно разместить. Многие ошибки 401 связаны не с самим ключом, а с заголовками запроса, Base URL или статусом активации модели.

Ниже разобрана цепочка «регистрация — создание — настройка — диагностика — ротация», а также различия между официальным ключом и ключом шлюза.

Примечание: Seedance, ByteDance, Doubao, Volcengine и Volcengine Ark — названия и товарные знаки их правообладателей. Статья носит технический характер и не означает партнёрства, агентского или лицензионного статуса; интерфейсы и цены определяются официальной документацией и материалами на сайте.

1. Сначала разделите аккаунт, модель и ключ

Вызов Seedance включает три уровня: платформенный аккаунт, сервис модели и учётные данные доступа. Аккаунт отвечает за верификацию и биллинг, модель нужно отдельно активировать на платформе, а API Key служит лишь идентификатором при запросе. Все три элемента обязательны и не заменяют друг друга.

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

Официальные интерфейсы данных обычно используют Authorization: Bearer <API_KEY>; интерфейсы управления (создание ключей и Endpoint) чаще требуют подписи AK/SK. Назначение у этих учётных данных разное — не вставляйте управленческие AK/SK в запросы к данным.

2. Маршрут A: официальный ключ Volcengine Ark

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

  1. Зарегистрируйте аккаунт Volcengine и пройдите верификацию и необходимые шаги с данными организации.
  2. Войдите в консоль Volcengine Ark и активируйте нужную модель Seedance; без активации вызов часто возвращает ошибку вида ModelNotOpen.
  3. Найдите страницу управления API Key и создайте ключ. В имени укажите назначение и среду, например seedance-prod-server.
  4. Скопируйте и сразу сохраните секрет. Большинство платформ показывает полное значение только при создании — после закрытия страницы его не восстановить.
  5. Отправьте короткую задачу с минимальными параметрами и убедитесь, что аутентификация, активация модели, квота и биллинг работают.
  6. Поместите ключ в серверные переменные окружения или в сервис управления секретами — не оставляйте его в коде, документации или переписке.

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

3. Маршрут B: ключ через совместимый шлюз

Если команда уже использует единый API-шлюз, отдельный облачный аккаунт обычно не нужен. После регистрации в ZSQH AI Gateway можно создать ключ в консоли, а затем в списке моделей проверить, активирован ли видеоканал Seedance и какие модели и параметры поддерживаются.

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

Регистрация доступна на странице ZSQH AI Gateway, доступные модели и принципы оплаты — в разделе цены на модели. Цены могут меняться; перед заказом ориентируйтесь на значения на странице.

4. Как выбрать между официальным ключом и ключом шлюза

Критерий Официальный ключ Volcengine Ark Ключ совместимого шлюза
Аккаунт и верификация Нужен аккаунт Volcengine и подтверждение Регистрация по правилам шлюза
Base URL Официальный адрес данных Адрес, выданный шлюзом
Объём прав Ограничен аккаунтом, активацией модели и квотой Ограничен настройками моделей и лимитами шлюза
Биллинг Официальный счёт Счёт шлюза, цены на странице
Подходящие сценарии Прямой доступ и собственное управление облаком Единый вход для многих моделей и меньше обслуживания аккаунтов
На что обратить внимание Для управления нужны AK/SK Сначала уточните видеоканал и поддержку колбэков

Критерий выбора — не «где дешевле», а способность команды нести обслуживание аккаунта, проверки соответствия и разбор инцидентов. Цена лишь один из факторов; стабильность и переносимость не менее важны.

5. Ключ в переменных окружения

И официальный ключ, и ключ шлюза не должны быть захардкожены. Ниже минимальный пример через переменные окружения:

# .env только для локальной работы, обязательно добавьте в .gitignore
export ARK_API_KEY="your-volcengine-ark-key"
export SEEDANCE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

# Дымовой тест: проверяем только аутентификацию и создание задачи
curl -sS -X POST "$SEEDANCE_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [{"type": "text", "text": "Городская улица после дождя, плавный наезд камеры, кинематографично"}],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

Идентификатор модели и параметры в примере лишь демонстрируют форму запроса; актуальные значения копируйте из консоли или официальной документации. В Python читайте значение через os.environ, в Node.js — через process.env; в CI используйте секреты платформы, в production — сервис управления ключами. Перед записью в лог маскируйте Authorization, чтобы ключ не попадал в систему логирования вместе с отчётами об ошибках.

6. Порядок диагностики 401

При 401 не начинайте с повторов — исключайте причины по порядку:

  • Заголовок строго Authorization: Bearer <key>, после Bearer обязателен пробел.
  • В ключе нет перевода строки, кавычек или лишних пробелов — частая проблема при копировании из консоли.
  • Base URL соответствует платформе, выдавшей ключ. Официальный ключ с адресом шлюза и ключ шлюза с официальным адресом не пройдут аутентификацию.
  • Ключ не отключён, не удалён и не истёк. После передачи дел в команде часто остаётся старый ключ, а код уже не обновлён.
  • На аккаунте нет задолженности, сервис активирован. Иногда такие ситуации возвращают 403, а не 401, — проверяйте обе.
  • Регион и Endpoint корректны. Адреса разных регионов нельзя смешивать; для трансграничных вызовов учитывайте сетевой маршрут.

401 означает лишь то, что идентификация не пройдена; слепые повторы проблему не решат. Сначала выведите маскированные заголовки, целевой адрес и тело ответа, затем сверяйте по пунктам.

7. Чек-лист безопасности ключа

  • Один ключ на среду: разработка, тестирование и production раздельно — при утечке последствия ограничены.
  • Минимальные права: активируйте только нужные бизнесу модели; в корпоративном аккаунте используйте IAM-пользователей и AK/SK для управления.
  • Не отдавайте на фронтенд: ключ остаётся на сервере, а сайт и приложение обращаются через собственный бэкенд.
  • Не храните в открытом виде: конфигурационный центр должен шифровать секреты, база не должна содержать полный ключ.
  • Следите за аномалиями: настройте оповещения о квоте, резком росте вызовов, подозрительных IP и доле ошибок.
  • Ведите аудит: фиксируйте, кто и когда создал ключ и где он использовался, минимум за один цикл ротации.

8. Ротация и действия при утечке

Регулярная ротация снижает риск долгосрочной утечки. Рекомендуемый порядок:

  1. Создайте новый ключ с датой в имени, например seedance-prod-202610.
  2. Запишите его в конфигурационный центр и сначала примените на одном инстансе или в одной среде.
  3. Прогоните минимальную цепочку «отправка — опрос — скачивание» и убедитесь, что биллинг и квота в норме.
  4. После полного переключения наблюдайте 24–48 часов и убедитесь, что вызовы со старым ключом исчезли.
  5. Отключите и удалите старый ключ, проверьте логи и счета на подозрительные вызовы.

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

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

Seedance API Key и пароль от аккаунта Volcengine — одно и то же?

Нет. Ключ используется только для аутентификации в API и не подходит для входа в консоль; пароль нужен для входа и управления аккаунтом. Храните их раздельно и не записывайте в одном месте.

Ключ верный, но всё равно возвращается 401. Почему?

Частые причины: неверный формат заголовка, пробелы или перевод строки при копировании, несовпадение Base URL и платформы ключа, отключённый ключ, а также проблемы со статусом аккаунта или сервиса. Сначала выполните минимальный запрос через curl, затем исключайте причины по одной.

Можно ли одним ключом вызывать текстовые и видеомодели?

Зависит от активации и прав на платформе. Даже в одном аккаунте разные модели активируются отдельно; перед вызовом проверьте доступность в консоли и ориентируйтесь на фактический ответ.

Можно ли хранить ключ во фронтенде сайта или приложения?

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

Как часто менять ключ?

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

Что дальше

Определите, идёте ли вы через официальный канал или шлюз, затем создайте отдельный ключ и выполните дымовой тест самой короткой задачей. Если нужен единый вход, зарегистрируйтесь в ZSQH AI Gateway и на странице цены на модели уточните видеоканал Seedance и правила биллинга.

Полезные материалы: