Видеоинтерфейс Kling использует асинхронные задачи, и первый шаг интеграции — не написать запрос, а получить учётные данные, положить их в правильное место и ограничить права. Многие ответы 401 и 403 связаны не с кодом, а с неполной копией ключа, неработающей переменной окружения или аккаунтом, которому не открыта нужная модель.
Ниже порядок «создание — настройка — диагностика — ротация» и типовые формы учётных данных открытой платформы Kling в 2026 году. Детали интерфейса меняются быстро; сверяйтесь с консолью и официальной документацией.
Примечание: Kling и Kuaishou — товарные знаки их правообладателей. Статья носит технический характер; автор не связан с указанными компаниями и не выступает их агентом.
1. Определите, какие учётные данные нужны
У Kling распространены две формы аутентификации:
- API Key: создаётся в консоли разработчика и передаётся в
Authorization: Bearer <API_KEY>. Новый интерфейс различает модели по пути; этот способ предпочтителен. - AccessKey + SecretKey: в основном для старого интерфейса. При каждом запросе SecretKey подписывает JWT, который затем помещается в заголовок Bearer. AccessKey указывается в утверждении
iss.
Требования безопасности различаются: API Key — долгосрочная строка, и при утечке её можно сразу использовать; SecretKey — ключ подписи, и при утечке злоумышленник сможет сам выпускать токены. В любом случае их нельзя писать во фронтенд, мобильный пакет или публичный репозиторий.
2. Как создать ключ Kling API
Вход в консоль международного сайта — https://kling.ai/dev/api-key; после входа в аккаунт Kling можно управлять ключами. Китайский вход и доступные модели определяются официальной страницей — не собирайте домен по сторонним руководствам.
- Войдите в консоль разработчика и откройте страницу управления API-ключами.
- Нажмите «+ Create a new API Key» и назовите ключ по схеме «проект — среда — назначение», например
video-prod-cn,video-test. - Сразу скопируйте и сохраните ключ. Страница обычно показывает его один раз; после закрытия полное значение недоступно.
- Запишите ключ в менеджер паролей или облачный сервис секретов, а также зафиксируйте автора, назначение и дату ротации.
- Проверьте аутентификацию задачей минимальной стоимости и сохраните
request_idдля будущей диагностики. - Убедитесь, что аккаунт купил подходящий пакет или подключил постоплату, и только затем начинайте рабочую интеграцию.
Именование — не формальность. При аномальных вызовах вы быстро определите по названию, какой сервис и среда виноваты, вместо остановки всех бизнес-процессов.
3. Старые AccessKey/SecretKey и JWT
В старом интерфейсе модель задаётся в теле через model_name, а JWT генерируется самостоятельно. Официальные правила: подпись HS256, iss содержит AccessKey, exp — текущее время плюс 1800 секунд, nbf — текущее время минус 5 секунд.
import os
import time
import jwt # PyJWT
access_key = os.environ["KLING_ACCESS_KEY"]
secret_key = os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{
"iss": access_key,
"exp": int(time.time()) + 1800,
"nbf": int(time.time()) - 5,
},
secret_key,
algorithm="HS256",
headers={"alg": "HS256", "typ": "JWT"},
)
print(token)
Несколько частых ошибок:
expзадаётся в секундах Unix, не в миллисекундах; значение в миллисекундах даст токен, который истечёт очень нескоро, но платформа может его сразу отклонить.- Синхронизируйте время сервера. При большом расхождении проверка
nbfне пройдёт, и появится сообщение «токен ещё не действует». - JWT действует всего 30 минут; при длительном опросе задачи его нужно перегенерировать, а не использовать один токен до конца.
- Не смешивайте JWT и API Key. Новый интерфейс использует API Key, старый — подпись AK/SK; ориентируйтесь на документацию конкретного интерфейса.
4. Права, пакеты и лимиты параллельности
Основная ошибка прав в документации Kling — бизнес-код 1103 (HTTP 403): «нет права на вызов этого API или модели». Обычно она связана со статусом аккаунта, подключением модели и пакетом, а не с недействительным ключом.
Различайте три вида ограничений:
- Статус аккаунта:
1100— аномальный статус;1101— задолженность по постоплате;1102— пакет исчерпан или просрочен. - Права на модель:
1103— у аккаунта нет права на этот интерфейс или модель. - Лимит параллельности: видеозадачи получают слоты по пакету; при превышении возвращается
1303. Официальная документация прямо указывает, что все API-ключи одного аккаунта используют общий пул.
Это значит, что «создать несколько ключей» не увеличит параллельность и не изолирует production от теста. Для жёсткой изоляции нужны отдельные аккаунты или отдельные пакеты, а в архитектуре — очередь задач. В документации Kling сейчас нет детальных scope вроде «только чтение» или «только генерация»; права привязаны к аккаунту и купленным возможностям. Если консоль позже добавит гранулярную авторизацию, ориентируйтесь на неё.
5. Хранение ключа в переменных окружения и менеджере секретов
Минимальное требование — переменные окружения; в production используйте Secrets Manager облачного провайдера, Kubernetes Secret или аналогичный сервис. Не коммитьте ключ в Git и не печатайте полное значение в логах.
Рекомендуемые имена переменных:
KLING_API_KEY=...
KLING_ACCESS_KEY=...
KLING_SECRET_KEY=...
KLING_BASE_URL=https://api-singapore.klingai.com
В репозитории храните только .env.example с заглушками. При старте приложение должно проверять наличие переменных и падать сразу, а не отправлять запрос с пустой строкой. В логах допускаются первые и последние 4 символа ключа и request_id. Браузер и мобильное приложение не должны держать ключ; все видеозадачи отправляются через бэкенд.
6. Таблица разбора 401
| Код | HTTP | Значение | Частая причина | Что делать |
|---|---|---|---|---|
| 1000 | 401 | Ошибка аутентификации | Неверный формат заголовка | Проверьте наличие Authorization |
| 1001 | 401 | Пустой заголовок авторизации | Пустая переменная, прокси удалил заголовок | Выведите длину переменной, проверьте пересылку через шлюз |
| 1002 | 401 | Неверные учётные данные | Ключ скопирован не полностью, отозван, не та среда | Создайте новый ключ и обновите секрет |
| 1003 | 401 | Токен ещё не действует | Сдвиг часов сервера, неверный nbf |
Синхронизируйте NTP, проверьте единицы времени |
| 1004 | 401 | Токен истёк | Старый JWT старше 30 минут | Сгенерируйте JWT заново |
Порядок диагностики — снаружи внутрь: сначала убедитесь, что заголовок действительно отправлен, затем что ключ относится к текущей среде, и только потом подозревайте платформу. Если используется обратный прокси или Serverless-платформа, проверьте, не фильтрует ли она заголовок Authorization.
7. Прямое подключение или API-шлюз
При прямом подключении к открытой платформе Kling аккаунт, пакеты, журналы вызовов и счета находятся у вас; это подходит командам с опытом закупки и эксплуатации. Через API-шлюз можно объединить несколько видеомоделей под одним ключом и одним счётом, сократив затраты на интеграцию.
При выборе шлюза уточните четыре вещи: открыт ли видеоканал Kling, поддерживаются ли асинхронные задачи и external_task_id без изменений, передаётся ли адрес callback, как выдаются ссылки на результаты. Шлюз, поддерживающий только OpenAI-совместимый текстовый интерфейс, не подходит для видеозадач. Посмотрите модели и тарифы и при необходимости зарегистрируйтесь для теста: сначала проверьте минимальную задачу, затем решайте о переносе production-трафика.
8. Ротация и действия при утечке
Ротация ключей должна быть регулярной процедурой, а не аварийной мерой. Рекомендуется менять ключ каждые 90 дней, а также сразу при уходе сотрудника или передаче проекта.
- Создайте в консоли новый ключ с датой в названии, например
video-prod-20261019. - Запишите новый ключ в менеджер секретов, обновите тестовую среду и прогоните самую короткую задачу.
- Постепенно обновите production, наблюдая за 401, 403 и успешностью задач.
- Убедившись в стабильности нового ключа, отзовите старый.
- Зафиксируйте дату ротации, исполнителя и затронутые сервисы.
При подозрении на утечку сначала отзовите старый ключ, затем проверьте журналы вызовов и счета, и только потом ищите путь утечки. Если изменить только код, но не отозвать учётные данные, риск сохраняется. Webhook Secret — отдельные учётные данные; официально старый и новый secret могут сосуществовать 7 дней, поэтому их можно ротировать независимо от API Key.
Частые вопросы
Чем API Key отличается от AccessKey/SecretKey?
API Key — одна строка, которая передаётся в заголовке Bearer; AccessKey/SecretKey — старая схема подписи, где JWT генерируется самостоятельно. Для нового интерфейса используйте API Key, для старого — JWT по документации.
Можно ли создать несколько ключей на одном аккаунте? Увеличится ли параллельность?
Можно создавать ключи для разных сред и проектов, но официальная документация указывает, что все ключи одного аккаунта используют общий пул параллельности; дополнительные ключи её не увеличивают. Для жёсткой изоляции нужны отдельные аккаунты или пакеты.
Ответ 401 «неверные учётные данные», но ключ выглядит правильным. Что проверить?
Проверьте, скопирована ли строка полностью, нет ли пробелов и переводов строк, отправлен ли запрос в правильный регион, не изменяет ли прокси заголовок Authorization. Если проблема остаётся, создайте новый ключ и сравните поведение.
Истекает ли ключ Kling API?
Сам API Key обычно не имеет фиксированного срока, но может перестать работать из-за отзыва, статуса аккаунта или изменения прав. Старый JWT действует 30 минут. Конкретные правила — в консоли и официальной документации.
Нужно ли регистрировать аккаунт Kling при работе через API-шлюз?
Не обязательно. Шлюз обычно берёт на себя аккаунт поставщика и биллинг, но доступные модели, параллельность, callback и политика хранения данных определяются шлюзом. До интеграции уточните, открыт ли видеоканал, и прочитайте условия обслуживания.
Читайте также:
