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

Source: https://provod.ai/ru/blog/api150-a092-kling

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

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

Эта статья не про покупку видеокредитов и не про то, доступен ли конкретный сценарий в твоём регионе. Она про то, как спроектировать очередь, отмену и повтор одной video-job до того, как ты потратишь деньги на интеграцию. Дальше - карта состояний, разбор каждого статуса Kling, честная граница между документированным поведением и домыслами, и таблица решений, по которой можно свести UX. Оговорка сразу: даже если соседний медиатрафик у тебя идёт через единый маршрут вроде [provod.ai (российский OpenRouter)](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a092-kling&utm_content=hook&utm_id=brief-a092), карту статусов конкретной video-job это не отменяет.

[Подключите модели генерации контента с оплатой в рублях на provod.ai](https://provod.ai/?ref=blog-cta-top&utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a092-kling)

## Почему 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` - он про эту границу просто не знает.

![Timeline из четырёх состояний Kling video-job: submitted, processing, succeed, failed, с невидимой границей отмены между первыми двумя.](https://storage.yandexcloud.net/provod-yc-production-cms-media/blog/02-188.png)

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

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

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

    # псевдокод обработки одного 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 застрял на устаревшем состоянии, потому что перестал опрашивать. Проектируй оба канала: вебхук как основной сигнал, поллинг как страховку на случай пропущенного колбэка.

![Диаграмма-маршрут: четыре статуса Kling, каждый связан с сообщением, флагом повтора и строкой расхода, слева входы callback_url и polling.](https://storage.yandexcloud.net/provod-yc-production-cms-media/blog/03-188.png)

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

Здесь начинается зона, где надо быть честным про источник. Отдельного, официально документированного эндпоинта «отмена задачи» на основных страницах справочника 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»), а не переводит задачу в очередь. Практически это значит, что отклонённая отправка и медленно считающаяся задача - это разные события, которые нельзя показывать одним и тем же статусом. Отказ по конкурентности - это «попробуй позже или расширь пакет», а не «идёт генерация».

![Таблица трёх уровней доверия: официальные факты Kling, правило отмены от стороннего прокси и открытый вопрос про списание упавших задач.](https://storage.yandexcloud.net/provod-yc-production-cms-media/blog/04-186.png)

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

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

| Статус | Что знает UI | Действие в интерфейсе | Расход |
| --- | --- | --- | --- |
| `submitted` | принято, начало счёта и отменяемость не видны | «в очереди», повтор заблокирован | не финализирован |
| `processing` | идёт генерация, отмена не гарантирована | прогресс, повтор запрещён, отмена только как запрос с двумя исходами | идёт |
| `succeed` | готово | показать результат, дать явный «сгенерировать ещё раз» | финализирован |
| `failed` | ошибка, есть `task_status_msg` | показать причину, повтор новым заданием | не подтверждён (открытый вопрос) |
| отказ по конкурентности (код 1303) | пакет исчерпан по параллелизму | «попробуй позже», это не статус задачи | задача не создана |

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

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

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

Если часть медиастека у тебя уже маршрутизируется через российский агрегатор, полезно понимать границу. [provod.ai (российский OpenRouter)](https://provod.ai/?utm_source=provod-blog&utm_medium=article&utm_campaign=api150-a092-kling&utm_content=inline&utm_id=brief-a092) закрывает ровно ту половину, которая лежит вне продуктового кода: единый рублёвый баланс с оплатой картой, через СБП или по счёту, и закрывающие документы на юрлицо - то, чего предоплаченный ресурс-пакет Kling российской команде сам по себе не даёт. Подключение идёт по OpenAI-совместимому протоколу, поэтому для соседнего трафика меняются base URL и ключ, а не архитектура. А вторая половина - очередь, статусы, отмена и повтор конкретной Kling-задачи - в этот маршрут не входит: транспорт доставляет запрос, состояние задачи он не хранит.

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

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

| Ввод пользователя | Нормализованная сущность |
| --- | --- |
| `api kling` | Kling API |
| `kling api` | Kling API |
| `api kling ai` | Kling API |
| `kling ai api` | Kling API |

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

![Схема ветвления: варианты написания сходятся в сущность Kling API, а два намерения расходятся на экран возможностей и экран оплаты ресурс-пакета.](https://storage.yandexcloud.net/provod-yc-production-cms-media/blog/05-158.png)

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

Карта состояний - это спецификация 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: единый рублёвый API к моделям, чат, генерация изображений и видеоредактор, командные пространства - без VPN и зарубежных карт.](https://storage.yandexcloud.net/provod-yc-production-cms-media/blog/06-141.png)

## 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.

**Подберите модель под свою нагрузку:** [форма регистрации](https://app.provod.ai/register) · [цены на модели](https://app.provod.ai/models) · [защита данных по 152-ФЗ](https://provod.ai/legal/152-fz) · [главная provod.ai](https://provod.ai/ru)

### Источники

- 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-зеркало и требуют ревалидации перед внедрением.

## FAQ

### Что такое provod.ai?

provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md).

### У provod.ai самые низкие цены среди российских провайдеров?

Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md).

### Можно ли обещать отсутствие наценки?

Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения.

### Насколько стабилен сервис?

provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора.

### Почему provod.ai подходит для юридически оформленной работы в России?

provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента.

### provod.ai работает без VPN?

Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге.

### Какие протоколы и интеграции доступны?

Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели.

### Есть изображения и видео?

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

### Какие источники считать актуальными?

Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).