Углублённый разбор Kling 3.0 Omni API: многокадровая генерация видео и физическая согласованность
Целевая модель:
kling-v3-omni
Эндпоинт инференса:https://api.toapis.com/v1/videos/generations
Связанные материалы: Руководство по автоматизации Kling 3.0 Turbo · Руководство по Kling V4 Flash API · Справочник kling-v3-omni · Model guide kling-v3-omni
1. Краткое содержание и обзор (TL;DR)
- Сначала каталог: черновики планирования иногда пишут
kling-3-omni. Эта строка не является документированным публичным ID. Проверка официального справочника генерации и страницы model-guide (HTTP 200) 2026-11-18 показывает фиксированное значениеmodelkling-v3-omni. Отправляйте именно эту строку. - Контракт: отправляйте задания асинхронно на
POST /v1/videos/generations, затем опрашивайтеGET /v1/videos/generations/{id}доcompletedилиfailed. Обычные задачи также можно запрашивать черезGET /v1/tasks/{id}. Официальные примеры используютhttps://toapis.com(иhttps://toapis.cnдля материкового Китая). Другие руководства этой серии используютhttps://api.toapis.com. Выберите один origin и придерживайтесь его. - Поля
shots[]нет: непрерывность нескольких планов и физическая согласованность — это задача промпта и опорных активов. Используйте официальные плейсхолдеры<<<image_N>>>,<<<video_N>>>и<<<element_N>>>вместе сmetadata.image_list,video_listиmetadata.element_list. Порядок списков должен совпадать с порядком плейсхолдеров; система не вставит плейсхолдеры и не добавит первый кадр автоматически. - Медиа: отправляйте только публичные URL
http://илиhttps://. Локальные файлы загружайте черезPOST /v1/uploads/imagesи используйте возвращённый URL. Не отправляйте base64.audioиvideo_listвзаимно исключают друг друга. - Непроверенные утверждения, которые нужно отбросить: черновые ставки вроде
$0.022/s, SLA 99,95% или собственная схемаshotsне являются текущей документацией ToAPIs. Живые тарифы и доступность канала подтверждайте в аккаунте.
2. Официальный ID Omni, плейсхолдеры и рабочие процессы согласованности
В поле model используйте публичное имя модели. Не подменяйте его псевдонимом из черновика, URL-slug или смежным, но другим ID каталога.
| ID каталога | Роль в этом руководстве | Документированные задачи |
|---|---|---|
kling-v3-omni | Основной ID статьи | Текст в видео плюс официальные ссылки Omni: image_list, video_list и element_list |
kling-3.0-turbo | Парный ID для коротких роликов; см. руководство Turbo | Только текст в видео и image-to-video с первым кадром — это не контракт ссылок Omni |
kling-v3 | Связанный не-Omni ID v3 | Отдельный справочник генерации. Не отправляйте списки или плейсхолдеры Omni на этот ID, если его собственные документы этого не говорят |
Основные поля запроса kling-v3-omni:
| Поле | Документированные значения | Примечания |
|---|---|---|
prompt | Обязательная строка | Ссылайтесь на активы плейсхолдерами с нумерацией с 1 |
mode | std (по умолчанию) или pro | std соответствует 720P, pro — 1080P; тот же флаг задаёт разрешение тарификации |
duration | Целые 3–15 (по умолчанию 5) | Не ограничено 5 или 10 секундами |
aspect_ratio | Частые значения 16:9 (по умолчанию), 9:16, 1:1 | Если маркетинговая таблица параметров короче, приоритет у справочника генерации |
audio | Булево, по умолчанию false | true тарифицируется как Sound; несовместимо с video_list |
video_list | Не более одного клипа | Тарифицируется как Video. refer_type: base или feature. keep_original_sound: yes или no |
metadata.image_list | Публичные значения image_url | Необязательный type: first_frame или end_frame; для end_frame нужен first_frame |
metadata.element_list | Активы субъекта или роли | url плюс необязательные type (например image или video) и role |
watermark | Булево | Только включение / выключение |
client_business_id | Необязательная строка | В китайском справочнике Omni документировано как поле верхнего уровня (также принимается в metadata, предпочтителен верхний уровень). Затем можно запросить GET /v1/videos/generations/{client_business_id} |
Синтаксис плейсхолдеров нумеруется с 1 и должен совпадать с порядком списков:
| Синтаксис | Ссылается на |
|---|---|
<<<image_1>>> | Первый элемент metadata.image_list |
<<<video_1>>> | Первый (и, по китайскому справочнику, единственный) элемент video_list |
<<<element_1>>> | Первый элемент metadata.element_list |
Английская страница генерации иллюстрирует синтаксис списка через <<<video_2>>>. Китайский справочник ограничивает video_list одним клипом. Не отправляйте второе опорное видео, пока справочник вашего аккаунта не скажет иное.
Практический способ собрать многокадровые и физически согласованные клипы всё же есть:
- Зафиксируйте дугу первым и конечным кадрами. Поместите начальный кадр в
image_listсtype: "first_frame"и конечный — сtype: "end_frame". Упомяните оба в промпте (переход от<<<image_1>>>к<<<image_2>>>) и опишите движение, гравитацию и путь камеры между ними. - Закрепите идентичность через
element_list. Повторно используйте один и тот же URL субъекта и стабильныйrole(например"subject") в связанных заданиях, чтобы одежда, лицо и пропорции не «плыли» при смене описания камеры. - Заимствуйте движение через
refer_type: "feature". Направьте<<<video_1>>>на публичную опору по движению и попросите<<<element_1>>>следовать этому движению. Для редактирования исходного клипа (например замены фона) используйтеrefer_type: "base". - Явно связывайте задания. Документ статуса — это не Omni-специфичный API последнего кадра. Если следующий план должен начаться с предыдущего дубля, разместите публичный кадр или копию этого дубля и отправьте его как следующий
first_frame. Сохраняйте каждый идентификатор задачи.

Рисунок 1: image_list, video_list и element_list (только публичные URL) отправляются на POST /v1/videos/generations; опрашивайте тот же идентификатор задачи и читайте result.data[0].url только после status completed.
Для высокочастотных коротких черновиков без списков Omni используйте kling-3.0-turbo. Для другого контракта генерации Kling см. руководство Kling V4 Flash.
3. Продакшен-реализация: cURL и Python
Международные примеры этой серии используют https://api.toapis.com. Официальные документы предписывают пользователям материкового Китая https://toapis.cn. Держите один origin на среду. Пути, идентификаторы моделей и заголовок Bearer остаются теми же.
Шаг 1: отправка задания с первым и конечным кадром через cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
"mode": "std",
"duration": 5,
"aspect_ratio": "16:9",
"metadata": {
"image_list": [
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"}
]
}
}'
Задание только по тексту опускает metadata и плейсхолдеры. Задание «субъект плюс движение» использует video_list с refer_type: "feature" и metadata.element_list и не должно задавать audio: true.
Шаг 2: вспомогательные функции Python и цикл опроса
Фрагмент следует документированному пути статуса задачи и состояниям queued / in_progress / completed / failed. Перед релизом сверьте id, result.data[0].url и конверт ответа со справочником API для вашего аккаунта.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_ID = "kling-v3-omni"
DURATION_RANGE = range(3, 16)
def dispatch_omni(
prompt: str,
*,
model: str = DOCUMENTED_ID,
mode: str = "std",
duration: int = 5,
aspect_ratio: str = "16:9",
audio: bool = False,
image_list: list[dict] | None = None,
element_list: list[dict] | None = None,
video_list: list[dict] | None = None,
client_business_id: str | None = None,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-v3-omni; kling-3-omni is not a documented public ID")
if mode not in {"std", "pro"}:
raise ValueError("mode must be std or pro")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
if audio and video_list:
raise ValueError("audio and video_list are mutually exclusive")
if video_list and len(video_list) > 1:
raise ValueError("video_list is documented as at most one clip")
types = [item.get("type") for item in (image_list or [])]
if "end_frame" in types and "first_frame" not in types:
raise ValueError("end_frame requires first_frame")
payload = {
"model": model,
"prompt": prompt,
"mode": mode,
"duration": duration,
"aspect_ratio": aspect_ratio,
}
if audio:
payload["audio"] = True
if video_list:
payload["video_list"] = video_list
metadata = {}
if image_list:
metadata["image_list"] = image_list
if element_list:
metadata["element_list"] = element_list
if metadata:
payload["metadata"] = metadata
if client_business_id:
payload["client_business_id"] = client_business_id
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_omni(
"Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
image_list=[
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"},
],
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Храните версию шаблона промпта рядом с записью задачи, чтобы отличать изменение плейсхолдеров или порядка списков от правки формулировки. Скачивайте файл до expires_at; справочник статуса документирует окно хранения в 30 дней.
4. Обработка ошибок и матрица статусов
Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Успешный HTTP-запрос всё равно требует чтения status задачи. Ошибки запроса и причины status: failed (например content_policy_rejected, insufficient_user_balance или generation_timeout) см. в справочнике ошибок.
| HTTP или состояние задачи | Типичная категория | Рекомендуемое действие |
|---|---|---|
400 | Недопустимое поле, расхождение плейсхолдеров и списков, одновременно audio и video_list, или end_frame без first_frame | Подтвердите kling-v3-omni, что порядок плейсхолдеров совпадает с каждым списком, что медиа — публичные URL, и что взаимоисключающие поля не сочетаются |
401 | Отсутствующий или недействительный API-ключ | Обновите ключ в панели ToAPIs и проверьте заголовок Authorization: Bearer |
429 | Ограничение частоты или параллелизма | Соблюдайте Retry-After, если он есть; делайте паузу с джиттером; повторяйте только когда это безопасно |
5xx или таймаут клиента | Временная проблема шлюза или апстрима | Запросите существующий идентификатор задачи, прежде чем отправлять повторно |
status: queued или in_progress | Это не ошибка | Подождите и опросите снова; не создавайте второе задание |
status: failed | Генерация не удалась | Прочитайте error.code и error.message (и error.reason, если есть). Не повторяйте неизменённую нагрузку, отклонённую политикой |
5. Цены и FinOps ROI
Официальный китайский справочник Omni публикует карту тарификации. С её помощью выберите семейство SKU, затем читайте сумму, которую фактически котирует ваш аккаунт.
| Форма запроса | Спецификация тарификации |
|---|---|
mode=std, audio=false, без video_list | 720P |
mode=pro, audio=false, без video_list | 1080P |
mode=std, audio=true | 720P+Sound |
mode=pro, audio=true | 1080P+Sound |
mode=std, с video_list | 720P+Video |
mode=pro, с video_list | 1080P+Video |
Выгрузка страницы model-guide kling-v3-omni от 2026-11-18 показала справочную цену 12 кредитов / секунду и указала, что итоговая тарификация следует текущей котировке аккаунта. Страница не публиковала долларовую ставку в секунду для Omni и не разделяла Sound или Video на отдельные долларовые цифры. Не конвертируйте кредиты в валюту самостоятельно и не переиспользуйте черновые ставки вроде $0.022/s.
- Сначала черновите в более дешёвом документированном режиме. Итерируйте в
std(720P) и со средней длительностью, например 5 секунд, храните версионированный шаблон промпта и меняйте по одному списку ссылок за раз. - Отображаемая цена — не гарантия канала. Прежде чем прогнозировать список планов, подтвердите ID, SKU и доступность через
GET /v1/models?type=videoи живую котировку в аккаунте. - Контролируйте расходы на уровне промпта: не отправляйте повторно после таймаута клиента, пока не проверите статус задачи. Официальные контракты поставщиков часто добавляют обязательства или пороги предоплаты; тарификация ToAPIs обычно идёт по факту использования — подтверждайте действующие условия в аккаунте.
6. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: отправляйте kling-v3-omni, а не kling-3-omni; документированного поля shots[] нет; duration — 3–15 секунд, а mode выбирает 720P или 1080P; audio и video_list нельзя сочетать; всегда опрашивайте путь статуса generations и сохраняйте идентификатор задачи.
7. Чек-лист действий
- Создайте ключ на портале разработчика ToAPIs.
- Подтвердите, что
kling-v3-omniвиден для вашего ключа черезGET /v1/models?type=video— не отправляйтеkling-3-omni. - Прогоните дымовой тест фрагмента cURL с
image_listпервого и конечного кадра,mode: "std"иduration: 5. - Опрашивайте
GET /v1/videos/generations/{id}с ограниченным дедлайном и скачайте результат доexpires_at. - Далее: руководство по автоматизации Kling 3.0 Turbo для высокочастотных коротких черновиков, model guide kling-v3-omni для состояния живого каталога и руководство Kling V4 Flash, если нужен другой контракт Kling.







