Kling API: статусы, callback и безопасный мониторинг

Создайте локальную операцию до вызова

До отправки задания сервер создаёт operation ID, привязывает его к проекту и сохраняет минимальный статус queued. Внешний task ID, если он возвращён, становится дополнительным атрибутом, а не единственным ключом приложения. Так пользователь получает безопасный идентификатор для поддержки, даже если внешний ответ потерян, формат изменился или поставщик не прислал ID. Не используйте API-ключ, prompt или ссылку на исходный файл в качестве идентификатора. Локальная операция также позволяет проверить права пользователя до показа статуса и изолировать tenants друг от друга.

Опишите допустимые переходы состояния

Список статусов должен быть малым и однозначным: queued, submitted, processing, completed, failed, cancelled и review_required. Для каждого перехода укажите источник, разрешённость повтора и что увидит пользователь. Например, completed нельзя менять на processing из-за запоздалого callback, а failed после сетевой ошибки не всегда означает, что внешняя задача не принята. Обработчик сравнивает текущую версию операции и время события, затем отклоняет устаревший или невозможный переход. Это защищает интерфейс от «мигания» статуса и упрощает расследование.

Проверяйте callback до обработки

Не доверяйте входящему HTTP-запросу только потому, что он пришёл на известный URL. Подтвердите метод, размер тела, кодировку и текущую схему поля события. Если контракт предусматривает подпись, проверяйте её по актуальному документированному алгоритму и секрету, который хранится только на сервере; не придумывайте заголовок или формат. Если подпись или контракт не подтверждены, поместите событие в review и не меняйте состояние автоматически. Сохраняйте минимальные признаки проверки, а не весь payload с пользовательскими данными или секретами.

Дедуплицируйте и делайте обработчик идемпотентным

События могут прийти дважды, в другом порядке или после retry транспорта. Постройте ключ дедупликации из проверенного event ID, либо из разрешённого сочетания external task ID, типа события и версии состояния — только если это определено вашим контрактом. Перед записью берите блокировку или используйте атомарное условное обновление. Повтор одного события должен вернуть безопасный результат без повторной выдачи кредита, уведомления или удаления файла. Не считайте несколько callback доказательством нескольких завершённых задач: сначала проверяйте локальную операцию и разрешённый переход.

Отделите статус от результата и ссылки

Готовый статус не делает результат вечным, публичным или разрешённым к показу. Ссылка может истечь, принадлежать другому проекту или требовать отдельной проверки прав. Храните локальную запись результата с минимальным сроком, проверяйте привязку к tenant и выдавайте пользователю только разрешённый маршрут приложения. Исходные изображения и видео могут содержать персональные данные и объекты авторского права; основания, согласия и правила хранения определяет клиент и его юрист. Не обещайте срок хранения, географию данных или качество видео без текущего договора.

Наблюдайте очередь без утечки данных

Метрики должны отвечать на практические вопросы: сколько задач ждёт, сколько обработано, сколько не прошло проверку callback и сколько ушло в review. Логируйте operation ID, локальный статус, класс ошибки, версию обработчика и безопасную временную метку. Не записывайте заголовок Authorization, тело prompt, исходный файл или webhook secret. Для поддержки подготовьте поиск по ID операции и роли проекта. При всплеске ошибок сначала отличите ошибку схемы, прав, сети и обработки события; общий retry без классификации способен создать дубли и дополнительные расходы.

Проверьте сценарии до rollout

В тестовом окружении воспроизведите принятый ответ без callback, два одинаковых события, событие после deadline, неверную схему и завершение задачи с недоступной ссылкой. Убедитесь, что интерфейс показывает честный промежуточный статус и предлагает путь в поддержку, а не обещает срок готовности. Перед расширением нагрузки назначьте владельца rollback и ограничьте частоту polling, если он нужен как резерв. Поставщики и gateway меняют форматы и каталоги, поэтому регулярно сверяйте контракт; статья не заменяет live-документацию и не подтверждает функции Kling.

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. В нём нет реального ключа: это логика приложения, а не текущая спецификация внешнего API. До интеграции подтвердите маршрут, схему и ограничения в документации.

export function applyEvent(operation, event) {
  const allowed = { queued: ['submitted', 'failed'], submitted: ['processing', 'failed'], processing: ['completed', 'failed', 'review_required'] };
  if (!operation || !event || typeof event.type !== 'string') return { ok: false, reason: 'invalid_event' };
  if (!(allowed[operation.state] || []).includes(event.type)) return { ok: false, reason: 'stale_or_forbidden_transition' };
  return { ok: true, nextState: event.type, operationId: operation.id };
}
// Invoke after authenticating the event according to the current provider contract.

Проверьте синтаксис через node --check, добавьте аутентификацию, лимиты и отрицательные тесты. Не помещайте тело запроса, ответ целиком или заголовки авторизации в журнал.

Граница ответственности

Материал описывает защитные механизмы приложения, а не гарантии поставщика. Не передавайте в браузер, статью, тикет или журнал API-ключи, заголовки Authorization, cookie, исходные ключи поставщиков либо полный пользовательский контент.

Материалы для сверки

Внешние источники объясняют общие инженерные принципы. Они не подтверждают функции, тарифы, доступность или SLA RussiaAPI и сторонних моделей.

• RFC 9110: HTTP semantics
• OWASP: безопасность webhook