Kling API: как спроектировать очередь, отмену и повтор video-flow

Видеокредит исчезает быстрее всего не в момент нажатия кнопки «сгенерировать», а в момент, когда продукт не может ответить на простой вопрос: это задание уже готово или его нужно запускать заново. Пользователь видит спиннер, который крутится третью минуту, теряет терпение, жмёт «ещё раз» - и оплачивает вторую генерацию того же ролика. С точки зрения бухгалтерии это не баг интеграции. Это дизайн, в котором не описан жизненный цикл задачи.

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

Эта статья не про покупку видеокредитов и не про то, доступен ли конкретный сценарий в твоём регионе. Она про то, как спроектировать очередь, отмену и повтор одной video-job до того, как ты потратишь деньги на интеграцию. Дальше - карта состояний, разбор каждого статуса Kling, честная граница между документированным поведением и домыслами, и таблица решений, по которой можно свести UX. Оговорка сразу: даже если соседний медиатрафик у тебя идёт через единый маршрут вроде provod.ai (российский OpenRouter), карту статусов конкретной video-job это не отменяет.

Подключите модели генерации контента с оплатой в рублях на provod.ai

Почему video-flow - это процесс состояний, а не покупка кредита

Разница между «купить кредиты» и «спроектировать video-flow» - это разница между разовым событием и длительным процессом. Покупка ресурса - одна транзакция с понятным исходом. Генерация видео - это конечный автомат, который живёт секунды или минуты и по дороге может завершиться четырьмя разными способами. Продукт, который путает эти две вещи, ставит gate оплаты там, где нужен обработчик состояний.

Официальная модельная документация Kling (KlingAI Open Platform, доступ 2026-07-18) описывает ровно четыре значения поля task_status для видео-эндпоинтов - text-to-video, image-to-video и lip-sync: submitted, processing, succeed, failed. Отдельного значения queued или cancelled в перечислении на официальных страницах модели нет. Это важнее, чем кажется: весь UX очереди тебе придётся собрать поверх этих четырёх слов, потому что пятого состояния платформа тебе не даёт.

Распространённое допущение звучит так: если у Kling доступен управляемый motion control, продуктовая интеграция считай что решена. Это неверно. Наличие выразительной генерации ничего не говорит о том, как продукт переживёт ожидание, ошибку и отмену. Motion control отвечает за то, каким получится ролик. Lifecycle отвечает за то, потеряешь ли ты задачу и деньги, пока ролик считается. Это два разных инженерных вопроса, и второй решается не богатством модели, а явной картой статусов.

Какие состояния есть у одной video-job?

Возьмём одну задачу и пройдём её целиком. Клиент отправляет запрос на генерацию и получает идентификатор задачи со статусом submitted - платформа приняла работу. Дальше задача переходит в processing - идёт вычисление. Финал один из двух: succeed с готовым результатом или failed с ошибкой. Четыре слова, три перехода, и на каждом из них у пользователя должно быть понятное сообщение и предсказуемое поведение кнопок.

Ключевая тонкость - в паре submitted/processing. Официальный enum не различает «ещё стоит в очереди и не начал считаться» и «уже начал считаться необратимо». Для продукта это два разных состояния: в первом отмена ещё может сработать, во втором - почти наверняка нет. Но task_status тебе эту границу не показывает. Значит, интерфейс не должен обещать пользователю отмену как гарантированную операцию на статусе submitted - он про эту границу просто не знает.

Как связать статус с действием пользователя и расходом

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

Разложить это удобно псевдокодом одной задачи. Ниже - минимальная карта переходов, где каждому из четырёх статусов сопоставлено сообщение и разрешение на повтор. Она нарочно тупая: цель не в изяществе, а в том, чтобы для каждого состояния существовала ровно одна ветка, и ни одно значение не проваливалось в «неизвестно».

# псевдокод обработки одного video-job (Kling task\_status) class UnexpectedStatus(Exception): pass

STATUS\_HANDLERS = { "submitted":  {"message": "Задание принято, ждём начала", "retry": False, "spend": "не финализирован"}, "processing": {"message": "Идёт генерация", "retry": False, "spend": "идёт"}, "succeed":    {"message": "Готово, показать результат", "retry": True, "spend": "финализирован"}, "failed":     {"message": "Ошибка, показать task\_status\_msg", "retry": True, "spend": "не подтверждён"}, }

def handle(task): status = task["task\_status"]           # одно из четырёх значений if status not in STATUS\_HANDLERS: raise UnexpectedStatus(status)     # неизвестный статус - это инцидент, а не тишина return STATUS\_HANDLERS[status]

На статусе failed официальный ответ несёт поле task_status_msg - это единственная документированная per-task поверхность причины отказа (например, запрос сработал против контентного риск-контроля платформы). Не прячь его. Пользователь, который видит «ошибка», жмёт повтор вслепую и снова платит. Пользователь, который видит причину, часто чинит запрос сам и повторяет осмысленно. Разница между этими двумя сценариями - одно поле, которое ты либо показал, либо проглотил.

Отдельно про то, как ты вообще узнаёшь о смене статуса. Опрашивать эндпоинт статуса в цикле - рабочий, но не единственный путь. Официальная платформа поддерживает асинхронный параметр callback_url: сервер «активно уведомляет» вызывающую сторону при изменении статуса задачи по отдельному документированному Callback-протоколу. Для длинных видео-задач вебхук снимает нагрузку с поллинга и убирает класс багов, где UI застрял на устаревшем состоянии, потому что перестал опрашивать. Проектируй оба канала: вебхук как основной сигнал, поллинг как страховку на случай пропущенного колбэка.

Что делать с отменой, если официального эндпоинта нет

Здесь начинается зона, где надо быть честным про источник. Отдельного, официально документированного эндпоинта «отмена задачи» на основных страницах справочника KlingAI Open Platform в этом исследовательском проходе (2026-07-18) найти не удалось. Единственное описанное правило отмены - «отменить можно только задачи в состоянии pending; как только задача перешла в processing, отменить её уже нельзя» - взято из стороннего реселлера/прокси PiAPI, который оборачивает модель Kling, а не из первичной документации kling.ai. Это не то же самое, что нативное поведение Kling.

Практический вывод из этого расхождения жёсткий. Поскольку официальный enum не содержит отдельного pending/queued рядом с submitted, клиент в принципе не может по одному task_status понять, отменяема ли ещё отправленная задача или она уже необратимо считается. Различие «pending против processing», где оно вообще задокументировано, живёт только на уровне стороннего прокси. Значит, в UI отмена - это запрос с двумя возможными исходами: «успели отменить» и «уже поздно». Проектируй сообщение под оба, и не обещай пользователю отмену как факт.

Если ты строишь на прокси-слое, где правило pending-only заявлено, - используй его, но пометь у себя как поведение конкретного слоя, а не Kling. Если строишь напрямую на официальном API - закладывай, что отмены может не быть вовсе, и тогда честная политика такая: не показывай кнопку отмены на processing, а вместо этого управляй ожиданиями через прогресс и таймаут. Отсутствие отмены - это тоже спроектированное поведение, если ты его явно описал. Незаданная отмена - это баг, который всплывёт первым же нетерпеливым пользователем.

Повтор и деньги: где именно сгорает кредит

Повтор нельзя проектировать в отрыве от расхода, иначе получается генератор двойных списаний. Официальная биллинговая документация говорит, что использование API разработчиком - предоплаченное: ресурс покупается отдельными пакетами (resource packages), отдельно от потребительских подписок, и списывается по мере выполнения задач генерации. Аккаунтная страница политики - канонический источник того, как именно расходуются единицы. Это меняет логику повтора: каждый повторный запуск - это новая оплачиваемая задача, а не бесплатная попытка «доделать» старую.

Теперь честная дыра. Ни на одной официальной странице в этом проходе не нашлось прямого утверждения, списывает ли failed или упавшая по таймауту задача единицы ресурс-пакета или проходит без списания. Вторичные блоги заявляют, что за упавшие задачи не берут плату, но против официальных страниц политики это не подтверждено. Поэтому в таблице решений строка расхода для failed помечена как «не подтверждён» - это открытый пункт на проверку по аккаунтной документации, а не установленный факт. Не строй экономику продукта на допущении, что ошибки бесплатны.

Есть ещё одно состояние, которое легко спутать с обычной ошибкой, а на деле оно про параллелизм. Официальная документация по лимитам привязывает ёмкость параллельных задач к купленному ресурс-пакету; превышение потолка конкурентности возвращает отдельную ошибку (в сообществе и у агрегаторов она проходит как код 1303, «parallel task over resource pack limit»), а не переводит задачу в очередь. Практически это значит, что отклонённая отправка и медленно считающаяся задача - это разные события, которые нельзя показывать одним и тем же статусом. Отказ по конкурентности - это «попробуй позже или расширь пакет», а не «идёт генерация».

Таблица решений: статус, знание UI, действие, расход

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

Строку про конкурентность держи отдельно от task_status намеренно: код 1303 приходит на отправке, до того как задача вообще получила статус. Смешать их в один индикатор - значит показать пользователю «генерация идёт» там, где на самом деле задача не создана.

Как это выглядит для российской команды

Здесь всплывает региональная деталь, которую нельзя обойти. Прямой доступ к страницам kling.ai и app.klingai.com в исследовательской сессии 2026-07-18 возвращал HTTP 446 (блокировка по региону); факты выше извлечены через поисковую выдачу и GitHub-зеркало, а не сплошным чтением страниц из России. Для команды это значит две отдельные задачи: доступ к самому API и оплата предоплаченного ресурс-пакета. Обе решаются вне продуктового кода, но обе влияют на то, дойдёшь ли ты вообще до этапа, где lifecycle имеет смысл.

Если часть медиастека у тебя уже маршрутизируется через российский агрегатор, полезно понимать границу. provod.ai (российский OpenRouter) закрывает ровно ту половину, которая лежит вне продуктового кода: единый рублёвый баланс с оплатой картой, через СБП или по счёту, и закрывающие документы на юрлицо - то, чего предоплаченный ресурс-пакет Kling российской команде сам по себе не даёт. Подключение идёт по OpenAI-совместимому протоколу, поэтому для соседнего трафика меняются base URL и ключ, а не архитектура. А вторая половина - очередь, статусы, отмена и повтор конкретной Kling-задачи - в этот маршрут не входит: транспорт доставляет запрос, состояние задачи он не хранит.

Что приходит на вход до того, как задача попадёт в очередь

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

Сложнее другое: два запроса выглядят соседними, а по намерению противоположны. Запрос «клинг моушен контрол бесплатно» - это про возможности модели, и ровно здесь допущение «выразительная генерация решает интеграцию» встречается с предоплаченным ресурс-пакетом. Запрос «купить кредиты клинг аи» - это уже про оплату, и человеку нужен не список фич, а экран пополнения. Свести оба намерения к одному экрану - тот же класс ошибки, что показать submitted и отказ по конкурентности одним индикатором: пользователь получает ответ не на свой вопрос и уходит жать кнопки наугад. Что именно умеет Kling сегодня, сколько стоят кредиты и на каких условиях они доступны из России - пункты на проверку, а не подтверждённые здесь факты.

Чего эта диаграмма не решает

Карта состояний - это спецификация UX, а не гарантия доступности. Она не подтверждает, что Kling доступен в твоём регионе, не подтверждает условия оплаты и не отвечает, спишется ли кредит за упавшую задачу. Всё это - внешние проверки, которые надо закрыть до реализации, а не после.

Диаграмма также не заменяет проверку версий. Версионирование Kling API (v1, v2.x, v3) может менять пути эндпоинтов и поля статусов; этот разбор отражает структуру документации на 2026-07-18 и требует ревалидации перед внедрением. Правило отмены «только в pending» остаётся поведением стороннего прокси-слоя, а не подтверждённой нативной способностью, и подавать его в UI как гарантию нельзя. И наконец, никакая карта состояний не сделает генерацию быстрее или дешевле - она лишь не даёт продукту терять задачи и списывать деньги дважды.

FAQ

Сколько статусов у задачи в Kling API и можно ли на них полагаться?

Официальная модельная документация описывает четыре значения task_status: submitted, processing, succeed, failed (KlingAI Open Platform, 2026-07-18). Отдельного queued или cancelled в enum нет. Полагаться на сами значения можно, но раскладку и порядок страниц - нет: доступ был через поиск и зеркало, а не сплошным чтением.

Есть ли у Kling официальная отмена задачи?

Отдельный официальный эндпоинт отмены на основном справочнике в этом проходе не найден. Единственное правило отмены - «только pending, после processing нельзя» - документировано сторонним прокси PiAPI, а не первичной документацией. Проектируй отмену как запрос с двумя исходами и не обещай её как гарантию.

Спишется ли кредит, если задача упала?

Не подтверждено. Официальная страница, прямо утверждающая, списывается ли failed/таймаут с ресурс-пакета, в этом проходе не найдена. Вторичные источники говорят «нет», но против аккаунтной политики это не проверено. Считай это открытым пунктом и не строй на нём экономику повтора.

Поллинг или вебхук?

Оба. Официальная платформа поддерживает callback_url и Callback-протокол для активного уведомления при смене статуса. Держи вебхук основным сигналом, а поллинг - страховкой на случай пропущенного колбэка.

Что значит ошибка при отправке, а не при генерации?

Превышение потолка параллельных задач возвращает отдельную ошибку (в сообществе - код 1303), а не переводит задачу в очередь. Это отказ на отправке: задача не создана. Не показывай его тем же индикатором, что и processing.

provod.ai — не переплачивайте мощной моделью за простую задачу

Разделяйте быстрые массовые запросы и сложные случаи: компактные модели берут рутину, флагманские — задачи, где критичны reasoning, контекст и качество результата.

В одном каталоге — актуальные модели для текста и медиа: GPT от OpenAI, Claude от Anthropic, Gemini от Google, Grok от xAI, DeepSeek, Qwen, GLM, Kimi и MiniMax; для изображений — Nano Banana 2 Pro и GPT Image; для видео — последние версии Seedance, Kling, Veo и Google Omni. Также доступны модели для reasoning, поиска, документов, эмбеддингов, музыки и аудио.

Оптимизация опирается на реальную стоимость: цены всех вариантов соответствуют официальным тарифам провайдеров 1:1, без наценки provod.ai.

Подберите модель под свою нагрузку: форма регистрации · цены на модели · защита данных по 152-ФЗ · главная provod.ai

Источники

• KlingAI Open Platform, model reference (text-to-video, image-to-video, lip-sync), доступ 2026-07-18 - четыре значения task_status и поле task_status_msg.
• KlingAI Open Platform, Callback Protocol, доступ 2026-07-18 - параметр callback_url и асинхронное уведомление.
• KlingAI Open Platform, rate limits, доступ 2026-07-18 - привязка конкурентности к ресурс-пакету и ошибка превышения (код 1303 по данным сообщества).
• KlingAI Open Platform, point policy / prepaid resource package, доступ 2026-07-18 - предоплаченная модель списания; списание за failed не подтверждено.
• PiAPI, cancel task / get task, доступ 2026-07-18 - правило «отмена только в pending» на стороннем прокси-слое, не подтверждённое как нативное поведение Kling.
• Примечание: доступ к kling.ai и app.klingai.com из сессии возвращал HTTP 446 (блокировка по региону); факты извлечены через поиск и GitHub-зеркало и требуют ревалидации перед внедрением.