Как использовать API Kling без прямого онбординга в Kling: руководство 2026 года

TL;DR Вы можете получать доступ к поддерживаемым видеомоделям Kling через CometAPI, используя учетную запись CometAPI и ключ API, без отдельной процедуры онбординга разработчика Kling. Текущий маршрут text-to-video — POST /kling/v1/videos/text2video. Он возвращает ID задачи, который ваш бэкенд опрашивает, пока задача не станет succeed или failed. Доступность моделей, параметры, цены и условия доступа учетной записи могут меняться, поэтому перед промышленным развертыванием проверьте актуальный каталог моделей и документацию по API.

Прямой ответ

Практический путь — каталог моделей Kling в CometAPI. Если нужная вам модель Kling доступна для вашей учетной записи CometAPI, ваш сервер может аутентифицироваться с помощью ключа API CometAPI и вызвать соответствующий совместимый с Kling endpoint. Для этого варианта отдельное приложение для Kling API не входит в шаги интеграции.

Это различие важно для команд, которые уже используют CometAPI для других моделей. Приложение сохраняет одну поверхность управления учетными данными и отношения с одним провайдером, добавляя при этом видеопроцесс Kling. Вашему коду по‑прежнему нужно использовать специфичную для видео Kling схему запроса и асинхронный жизненный цикл задачи; «один API‑ключ» не означает, что у всех провайдеров одинаковое тело запроса.

Эта статья фокусируется на text-to-video, потому что это наименьшая полезная интеграция. CometAPI также документирует image-to-video и другие процессы Kling, но у каждого свой endpoint и ограничения параметров. Начните с одного проверенного пути, затем добавляйте возможности только после проверки актуальной документации.

Почему этот путь может быть полезен для команды разработки

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

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

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

Что меняется в этом варианте доступа — и что не меняется

Что меняется. Вы создаете и управляете ключом CometAPI, отправляете запросы в совместимый с Kling API CometAPI и отслеживаете использование со стороны CometAPI. Это убирает отдельный шаг прямого онбординга Kling для данного пути доступа.

Что не меняется. Kling остается базовым семейством моделей. Специфичные для провайдера параметры, поведение генерации, правила приемлемого использования, доступность моделей и характеристики выходных данных по‑прежнему важны. Документация CometAPI также отмечает, что поля запросов и ответов у провайдеров могут отличаться, поэтому используйте актуальную ссылку на endpoint как контракт для вашей реализации.

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

Перед началом

Вам нужна учетная запись CometAPI, ключ API, хранящийся на вашем сервере, и бэкенд, способный выполнять асинхронные задания. Держите ключ в переменной окружения, например COMETAPI_KEY; не раскрывайте его в браузерном или мобильном клиентском коде.

1. Откройте каталог моделей Kling и убедитесь, что модель, которую вы планируете использовать, сейчас доступна для вашей учетной записи.
2. Изучите текущую документацию по Kling text-to-video. На момент проверки в примере используется kling-v3.
3. Создайте серверный ключ API в консоли CometAPI и задайте его в окружении выполнения.
4. Решите, где ваша служба будет хранить ID задачи и итоговое видео. Запрос на генерацию возвращает задачу, а не готовый видеофайл.

Выберите рабочий процесс Kling до проектирования запроса

Исходите из актива, который уже есть у вашего продукта. Если у пользователя только текстовая концепция, прямой путь — text-to-video. Если у пользователя есть статичное изображение, которое должно оставаться визуальной опорой, используйте отдельно документированный маршрут image-to-video. Не добавляйте поле изображения в запрос text-to-video и не предполагайте, что API сам определит процесс.

Текущая документация по image-to-video принимает публичный URL изображения или строку изображения в base64 и возвращает асинхронную задачу. Более специализированные процессы Kling имеют собственные страницы и ограничения запроса. Добавляйте их по одному, только когда это оправдано требованием продукта и текущей документацией.

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

Сделайте первый запрос Kling text-to-video

Текущий endpoint text-to-video принимает JSON и аутентификацию Bearer. Начните с короткого промпта и минимально поддерживаемой длительности. Следующий запрос использует только поля, показанные в текущей справке CometAPI:

curl https://api.cometapi.com/kling/v1/videos/text2video \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
    "model_name": "kling-v3",
    "mode": "std",
    "duration": "5",
    "sound": "off"
  }'

Успешная отправка возвращает объект, содержащий data.task_id и статус задачи. Сохраните этот ID задачи в записи задания вашего приложения. Не держите HTTP‑соединение открытым во время рендеринга видео.

Безопасно обрабатывайте асинхронную задачу

Генерация Kling — асинхронная. Для text-to-video опрашивайте GET /kling/v1/videos/text2video/{task_id}. Справка CometAPI по задачам говорит, что ответ может вернуть задачу напрямую или внутри оболочки data, поэтому пример нормализует обе формы. Он также трактует все нетерминальные состояния как «продолжать ждать», не полагаясь на фиксированный список промежуточных статусов.

import os
import time
import requests

API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def submit_video(prompt: str) -> str:
    response = requests.post(
        BASE_URL,
        headers=HEADERS,
        json={
            "prompt": prompt,
            "model_name": "kling-v3",
            "mode": "std",
            "duration": "5",
            "sound": "off",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["data"]["task_id"]


def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
    deadline = time.monotonic() + timeout_seconds
    poll_url = f"{BASE_URL}/{task_id}"

    while time.monotonic() < deadline:
        response = requests.get(poll_url, headers=HEADERS, timeout=30)
        response.raise_for_status()
        payload = response.json()
        task = payload.get("data") or payload
        status = task.get("task_status")

        if status == "succeed":
            videos = task.get("task_result", {}).get("videos", [])
            if not videos or not videos[0].get("url"):
                raise RuntimeError("Task succeeded without a video URL")
            return videos[0]["url"]

        if status == "failed":
            detail = task.get("task_status_msg") or task.get("task_result")
            raise RuntimeError(f"Kling task failed: {detail}")

        time.sleep(10)

    raise TimeoutError(f"Kling task {task_id} exceeded {timeout_seconds}s")


task_id = submit_video(
    "A small ceramic cup on a wooden table, steam rising in soft morning light"
)
video_url = wait_for_video(task_id)
print(video_url)

Терминальная строка успеха — succeed, а не succeeded. Когда задача завершена, скопируйте сгенерированный ассет в хранилище, которое вы контролируете, если вашему продукту требуется хранение. URL‑адреса доставки провайдера не следует считать постоянным хранилищем приложения.

Для больших нагрузок используйте очередь или воркеры, а не опрос внутри веб‑запроса. CometAPI также документирует callback URL для задач Kling. Если вы используете вебхуки, аутентифицируйте и дедуплицируйте события обратного вызова и сохраняйте опрос как запасной путь для пропущенных доставок.

Спроектируйте жизненный цикл задания приложения до масштабирования

Рассматривайте задачу провайдера как часть вашей собственной записи задания. Храните ID задания приложения, процесс, запрошенную модель, ID задачи провайдера, URL запроса, текущий статус, метку времени отправки, время последнего опроса и расположение результата. Это дает вашей службе поддержки и операторам достаточно контекста, чтобы исследовать неудачную или медленную генерацию без поиска по сырым логам запросов.

Не повторяйте запрос на создание только потому, что клиент не получил ответ. Провайдер мог уже создать задачу. Зафиксируйте локальное задание перед отправкой, немедленно сохраните возвращенный ID задачи и разделяйте ретраи создания и ретраи запроса статуса. Текущая справка по text-to-video также документирует external_task_id для трекинга; подтвердите его актуальное поведение, прежде чем полагаться на него как на механизм дедупликации.

const TERMINAL = new Set(["succeed", "failed"]);

function normalizeKlingTask(payload) {
  const task = payload?.data ?? payload;
  if (!task?.task_id || !task?.task_status) {
    throw new Error("Kling response is missing task identity or status");
  }
  return task;
}

async function refreshVideoJob(job, apiKey) {
  const response = await fetch(job.queryUrl, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    throw new Error(`Task query failed with HTTP ${response.status}`);
  }

  const task = normalizeKlingTask(await response.json());
  const outputUrl = task.task_result?.videos?.[0]?.url ?? null;

  return {
    ...job,
    providerTaskId: task.task_id,
    providerStatus: task.task_status,
    terminal: TERMINAL.has(task.task_status),
    outputUrl,
    failureDetail: task.task_status_msg ?? null,
    checkedAt: new Date().toISOString(),
  };
}

Этот пример намеренно не переводит каждый возможный промежуточный статус провайдера в продуктовые обещания. Ваш воркер удерживает нетерминальные задачи активными, явно обрабатывает succeed и failed и записывает сырой статус провайдера для отладки. Добавьте отдельный таймаут приложения, чтобы застрявшая задача не оставалась открытой бесконечно.

Используйте опрос как базу, потому что ID задачи можно запрашивать. Когда выбранный endpoint поддерживает callback_url, вебхук может сократить повторяющиеся запросы статуса, но он не должен быть вашим единственным механизмом восстановления. Официальное руководство по опросу и вебхукам отмечает, что полезные нагрузки callback могут быть специфичны для провайдера. Храните сырой эвент, делайте обработку идемпотентной по ID задачи, быстро возвращайте успешный HTTP‑ответ и согласовывайте терминальное состояние через опрос.

Чек‑лист для продакшена для команд разработки

• Валидируйте модель во время выполнения. Проверяйте текущий каталог и явно отказывайте, когда запрошенная модель недоступна. Не подменяйте молча другую модель, если поведение результата важно.
• Разделяйте отправку и получение. Храните ID задачи CometAPI, ваш собственный ID задания, выбранную модель и метки времени, чтобы ретраи не создавали дублирующую работу.
• Ограничьте опрос. Используйте таймаут, экспоненциальный бэкофф или разумный фиксированный интервал и максимальное число повторов. Ознакомьтесь с руководством по лимитам и конкуренции CometAPI перед ростом параллелизма.
• Классифицируйте ошибки. Не повторяйте запросы при неверных параметрах или ошибках аутентификации. Применяйте бэкофф к ретраибельным ошибкам лимитов и платформы, следуя текущему руководству по ошибкам и ретраям.
• Защитите учетные данные и входные данные. Держите ключи API на сервере, избегайте логирования секретов и убедитесь, что пользователи имеют права на любые промпты, изображения или другие исходные ассеты, которые они отправляют.
• Измеряйте все задание. Отслеживайте успешность отправки, время в очереди, время генерации, долю терминальных ошибок, долю таймаутов, успешность получения результата и стоимость по модели и режиму.
• Сохраняйте результаты осознанно. Скачивайте завершенные ассеты в ваше контролируемое хранилище, когда продукту нужен долговременный доступ, затем применяйте вашу политику хранения и удаления.

Практические вопросы и ответы

Нужна ли отдельная учетная запись разработчика Kling для этого пути?

Отдельного шага онбординга разработчика Kling не видно в потоке интеграции CometAPI. Вы используете учетную запись и ключ API CometAPI. Доступ по‑прежнему зависит от того, включена ли модель для вашей учетной записи и региона, поэтому подтвердите это перед переходом в продакшен.

Полностью ли API Kling совместим с OpenAI?

Нет, не для показанного здесь видеопроцесса. Он использует специфичные для Kling маршруты, такие как /kling/v1/videos/text2video, и специфичные поля. Вы можете управлять учетными данными через CometAPI, но ваш адаптер должен сохранять схему, специфичную для провайдера.

Какой ID модели Kling следует использовать?

Текущая справка CometAPI по text-to-video использует в первом рабочем примере kling-v3 и перечисляет несколько более ранних треков. Используйте ID модели из актуального перечисления endpoint и проверьте, что он включен для вашей учетной записи. Не предполагайте, что самая новая модель доступна везде.

Почему в первом ответе нет видео?

Генерация видео выполняется как асинхронная задача. Первичный ответ возвращает ID задачи. Опрашивайте соответствующий маршрут запроса статуса, пока task_status не станет succeed или failed, затем читайте метаданные результата.

Следует ли использовать опрос или callback URL?

Для первой интеграции проще опрос. Callback‑и снижают число повторных запросов на масштабе, но требуют аутентифицированного, идемпотентного получателя и логики восстановления. Многие продукционные системы используют callback‑и как основной путь и опрос как запасной.

Можно ли использовать image-to-video через тот же endpoint?

Нет. CometAPI документирует image-to-video под отдельным маршрутом /kling/v1/videos/image2video. Соблюдайте текущую схему запроса этого endpoint, а не добавляйте поле изображения в пример text-to-video.

Стоит ли начинать со стандартного или профессионального режима?

Используйте std, чтобы проверить аутентификацию, форму запроса, хранение задач, опрос и получение результата. Текущая справка описывает pro как режим более высокого качества и стоимости. Оценивайте его на репрезентативных промптах только после того, как базовый процесс работает, и сравнивайте качество вместе с временем генерации и фактической стоимостью.

Как избежать дублирующих генераций при ретраях?

Создайте запись задания приложения перед вызовом API и сразу сохраняйте возвращенный ID задачи провайдера. Повторяйте запросы статуса отдельно от запросов создания. Не предполагайте, что повторный POST является идемпотентным. Endpoint сейчас документирует external_task_id для трекинга, но подтвердите его текущую семантику, прежде чем считать его гарантией дедупликации.

Вывод

Для команды разработчиков из США, которая хочет протестировать генерацию видео Kling без отдельной прямой заявки разработчика Kling, CometAPI предоставляет документированный путь: убедитесь, что нужная модель Kling доступна для аккаунта, аутентифицируйтесь ключом CometAPI, вызовите endpoint, специфичный для процесса, и отслеживайте асинхронную задачу до терминального состояния.

Практическая инженерная ценность — централизованный доступ и повторно используемая модель задания приложения, а не предположение, что все видеопровайдеры ведут себя одинаково. Держите тонкий адаптер для каждого процесса, намеренно сохраняйте идентификаторы задач и результаты и сохраняйте опрос как путь восстановления, даже когда включены callback‑и.

Безопасный вывод в продакшен — небольшой и измеримый: валидируйте одну модель и один процесс, отправляйте короткие недорогие задания, фиксируйте долю успешных и ошибочных завершений, проверяйте получение результатов и сравнивайте фактические стоимость и задержки с требованиями продукта. Добавляйте image-to-video или другие процессы Kling только после того, как проверены текущая документация и целевая учетная запись.