Kling 3.0 Motion Control

Перенесите движения из одного видео длиной 3–30 секунд на персонажа с одного изображения в 720p или 1080p и выберите источник фона — видео или изображение. При ориентации по изображению результат длится до 10 секунд, по видео — до 30 секунд.

• Асинхронная обработка: запрос создания возвращает ID задачи. Видео будет доступно после её успешного завершения.
• Два обязательных материала: одно изображение персонажа и одно видео движений длиной 3–30 секунд. Персонаж с изображения повторяет движения из видео.
• character_orientation определяет, чему следует ориентация персонажа, и максимальную длительность результата: до 10 секунд при image по умолчанию, до 30 секунд при video.
• Поля duration нет: результат длится столько же, сколько видео движений, но не дольше ограничения выбранной ориентации.
• Оплата за секунду готового видео в 720p или 1080p. Итоговая стоимость рассчитывается из суммы, зарезервированной при создании. Задача, завершившаяся ошибкой, не оплачивается.

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Идентификаторы моделей

Две модели используют один адрес API и одинаковые входные данные. Значения ниже взяты непосредственно из контракта шлюза. Только Kling 3.0 Motion Control принимает background_source.

Адрес API и авторизация

POST https://api.beatapi.io/v1/videos/tasks

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Режимы ввода

Параметры запроса

Перед созданием задачи шлюз также проверяет следующие сочетания параметров:

• Требуются ровно одно изображение персонажа и одно загруженное видео движений длиной 3–30 секунд. При character_orientation: image результат не превышает 10 секунд.

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

• При создании задачи длительность проверяется только у видео движений: 3–30 секунд, по заголовку файла, с допуском 0,1 секунды. Сообщение указывает индекс материала с 0, как в ошибках полей: reference_videos[0] is 45 seconds long; this model takes reference video of 3 to 30 seconds.
• Если длительность нельзя прочитать — сервер не поддерживает запросы диапазона байтов или файл не MP4/MOV, — на этом этапе ролик не измеряется и не отклоняется. Создание отклоняется только при ошибке сервера или пустом файле, например reference_videos[0] could not be downloaded: the URL returned HTTP 404.
• Для роликов до 10 секунд используйте image. Для более длинного видео движений передайте character_orientation: "video".
• Размер файла, формат и размеры изображения при создании задачи не проверяются.
• Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url. Поддерживаются изображения png, jpg, jpeg, webp до 50 MB и видео mp4, mov до 100 MB.

Как ориентация влияет на длительность

Поля duration нет. Длительность результата совпадает с видео движений, но ограничена character_orientation.

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

Параметры, которые модель не принимает

Эти параметры не игнорируются, а отклоняются до списания средств:

• duration, aspect_ratio, generate_audio, seed, task_type, output_format, reference_images, reference_audios, quality, sound, watermark и другие поля видеомоделей → field "duration" is not supported by model kling-3-motion-control (с именем переданного поля).
• Поле, вообще неизвестное API → unknown field: <name>.

Примеры запросов

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
}'

Перенос движений

Замените ссылку собственным MP4 или MOV длиной 3–30 секунд: общедоступного примера видео нет. character_orientation не задан, поэтому используется image, а результат не превышает 10 секунд.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
}'

1080p, ориентация по видео

Для ролика длиннее 10 секунд: video допускает результат до 30 секунд. Замените ссылку собственным роликом. Большая длительность результата требует большего резерва при создании задачи.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "1080p",
  "character_orientation": "video"
}'

Сохранение фона изображения персонажа

Результат сохраняет фон изображения персонажа вместо фона видео движений. Замените ссылку на видео своим роликом.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p",
  "background_source": "input_image"
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 1.1,
      "billable_duration_seconds": 10
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 1.1,
      "credits_refunded": 0,
      "credits_charged": 1.1,
      "billable_duration_seconds": 10
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 0,
      "credits_refunded": 1.1,
      "credits_charged": 0,
      "billable_duration_seconds": 10
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

• Эти цены действуют после появления модели в списке. До этого запрос создания отклоняется без списания средств.
• Оплата за секунду готового видео по тарифу resolution. character_orientation и промпт на тариф не влияют. В таблице ниже указана цена 8-секундного результата.
• Результат длится столько же, сколько видео движений, поэтому при создании окончательная цена неизвестна. Шлюз резервирует максимум для выбранной ориентации: 10 секунд при image, 30 при video, по тарифу разрешения. Это примерно $1.10 (720p) или$1.40 (1080p) при image и $3.30 (720p) или$4.20 (1080p) при video. Баланс должен покрывать резерв, иначе создание возвращает 402 insufficient_credits.
• После завершения списание рассчитывается по данным об использовании для созданного видео, обычно по базовому тарифу за секунду его длительности. Остаток резерва возвращается. Если данные об использовании не получены, списывается резерв. usage.credits_charged и usage.credits_settled показывают списанную сумму. У этой модели usage.billable_duration_seconds показывает зарезервированные при создании секунды (10 или 30), а не длину готового видео. Фактическую оплату проверяйте по денежным полям.
• Если задача завершилась ошибкой, в том числе из-за модерации после отправки, резерв возвращается полностью. Отклонённый до создания задачи запрос не оплачивается.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Частые ошибки

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

Отличия двух моделей