Kling 3.0 Turbo API: архитектура автоматизации массового короткого видео
Целевая модель:
kling-3.0-turbo
Эндпоинт инференса:https://api.toapis.com/v1/videos/generations
Связанные материалы: Углублённый разбор Kling 3.0 Omni · Руководство по Kling V4 Flash API · Справочник kling-3.0-turbo · Model guide kling-3.0-turbo
1. Краткое содержание и обзор (TL;DR)
- Сначала каталог: черновики планирования иногда пишут
kling-3-turbo. Эта строка не является документированным публичным ID. Проверка официального справочника генерации и страницы model-guide (HTTP 200) 2026-11-18 показывает фиксированное значениеmodelkling-3.0-turbo. Отправляйте именно эту строку. - Контракт: отправляйте задания асинхронно на
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 и придерживайтесь его. - Документированный диапазон:
duration— любое целое от 3 до 15 секунд (по умолчанию5), а не только 5 или 10.resolution—720pили1080p(по умолчанию720p).aspect_ratio(16:9,9:16,1:1) применяется только к запросам «текст в видео». - Ввод изображения — только первый кадр. Если вы отправляете
reference_images, только первый публичный URL используется какfirst_frame. Конечный кадр в этой интеграции не поддерживается, дополнительные изображения игнорируются. Не отправляйте base64. - Непроверенные утверждения, которые нужно отбросить: черновые цифры вроде
$0.11за 5-секундный клип, задержки «менее 20 с», «30+ параллельных» воркеров, SLA 99,95% или заголовка «на 60% дешевле» не являются текущей документацией API. Цитируйте только живые числа каталога или model-guide и считайте их отображаемыми ставками, которые могут измениться.
2. Официальный ID Turbo и ограничения массовой обработки
В поле model используйте публичное имя модели. Не подменяйте его псевдонимом из черновика, маркетинговым отображаемым именем или смежным ID Omni.
| ID каталога | Роль в этом руководстве | Документированные задачи |
|---|---|---|
kling-3.0-turbo | Основной ID статьи | Текст в видео и image-to-video только с вводом первого кадра |
kling-v3-omni | Парный ID Omni; см. руководство Omni | Официальные ссылки image_list / video_list / element_list, включая первый и конечный кадры |
kling-v3 | Связанный не-Omni ID v3 | Отдельный справочник генерации. Не предполагайте, что поля Turbo там применимы |
Официальная страница генерации Turbo уже некоторых маркетинговых формулировок. Общий язык model-guide может упоминать дополнительные видеопроцессы; справочник API для этого ID документирует только текст в видео и image-to-video с первым кадром. Стройте автоматизацию по справочнику, а не по брошюре.
| Поле | Документированные значения | Примечания |
|---|---|---|
prompt | Обязательная строка | Для image-to-video отправляется как элемент содержимого prompt в Turbo |
reference_images | Необязательный массив строк | Только первое изображение используется как first_frame; остальные игнорируются |
resolution | 720p (по умолчанию), 1080p | Это не флаг Omni mode=std/pro |
duration | Целые 3–15 (по умолчанию 5) | Черновики, перечисляющие только 5 и 10 с, неполны |
aspect_ratio | 16:9 (по умолчанию), 9:16, 1:1 | Применяется только к тексту в видео |
watermark | Булево, по умолчанию false | Только включение / выключение официального водяного знака Kling; пользовательский объект не поддерживается |
Автоматизация высокочастотных коротких роликов — это задача оркестрации поверх этого контракта.
- Один клип — одна задача. Отправляйте каждый вариант как отдельное асинхронное задание. Сохраните идентификатор задачи (и свой request id) до начала опроса.
- Ограничивайте каждое ожидание. Используйте дедлайн, минимальный интервал 5–10 секунд с джиттером и
Retry-Afterпри429. Справочник статуса отмечает, что длинные видео могут занимать несколько минут; таймаут клиента не является сбоем, пока вы не запросили тот же id повторно. - Не выдумывайте SLA параллелизма. Официальные документы не публикуют зарезервированную квоту «30+ одновременных» для этой модели. Следите за ответами
429и справочником лимитов асинхронных задач. Пакетный запрос статуса принимает не более 100 идентификаторов задач. - Держите задания с изображениями честными. Если плану нужен конечный кадр, списки Omni или опорное видео движения, переключайтесь на
kling-v3-omni, а не перегружайте смысломreference_images.

Рисунок 1: отправляйте каждый короткий вариант на POST /v1/videos/generations, опрашивайте тот же идентификатор задачи ограниченным циклом и читайте result.data[0].url только после status completed.
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-3.0-turbo",
"prompt": "A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"resolution": "720p",
"duration": 5,
"aspect_ratio": "16:9",
"watermark": false
}'
Задание image-to-video добавляет "reference_images": ["https://example.com/first-frame.png"] и не должно полагаться на aspect_ratio или на второе изображение как на конечный кадр.
Шаг 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-3.0-turbo"
DURATION_RANGE = range(3, 16)
def dispatch_turbo(
prompt: str,
*,
model: str = DOCUMENTED_ID,
resolution: str = "720p",
duration: int = 5,
aspect_ratio: str = "16:9",
reference_images: list[str] | None = None,
watermark: bool = False,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-3.0-turbo; kling-3-turbo is not a documented public ID")
if resolution not in {"720p", "1080p"}:
raise ValueError("resolution must be 720p or 1080p")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
payload = {
"model": model,
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"watermark": watermark,
}
if reference_images:
payload["reference_images"] = reference_images[:1]
else:
payload["aspect_ratio"] = aspect_ratio
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")
def dispatch_batch(prompts: list[str], **kwargs) -> list[str]:
"""Submit every prompt first, then poll. A failed submit must not hide already-issued ids."""
task_ids = []
for prompt in prompts:
task_ids.append(dispatch_turbo(prompt, **kwargs))
return task_ids
if __name__ == "__main__":
variants = [
"A 5-second product teaser for a lightweight running shoe, street-level camera, clean daylight",
"The same shoe on a wet evening street, slower tracking shot, warm storefront light",
]
ids = dispatch_batch(variants, resolution="720p", duration=5)
for task_id in ids:
print("Task:", task_id)
print("Video:", poll_task(task_id))
Храните версию шаблона промпта рядом с каждой записью задачи, чтобы отличать изменение разрешения или duration от правки формулировки. Скачивайте каждый файл до expires_at; справочник статуса документирует окно хранения в 30 дней.
4. Обработка ошибок и матрица статусов
Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Успешный HTTP-запрос всё равно требует чтения status задачи. Ошибки запроса и причины status: failed (например content_policy_rejected, insufficient_user_balance или generation_timeout) см. в справочнике ошибок.
| HTTP или состояние задачи | Типичная категория | Рекомендуемое действие |
|---|---|---|
400 | Недопустимое поле, неподдерживаемые duration или resolution, или тип медиа, который интеграция не принимает | Подтвердите kling-3.0-turbo, что duration равен 3–15, что resolution — 720p или 1080p, и что любое изображение — публичный 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
Выгрузка страницы model-guide kling-3.0-turbo от 2026-11-18 показала следующие отображаемые сравнительные ставки и собственное примечание страницы о том, что цены могут измениться, а итоговая тарификация следует текущей цене аккаунта, duration, resolution, соотношению сторон и отправленным параметрам:
| Спецификация | Отображаемая ставка ToAPIs (2026-11-18) | Официальная отображаемая ставка на той же странице |
|---|---|---|
720p | $0.08 / секунда | $0.1143 / секунда |
1080p | $0.1 / секунда | $0.1429 / секунда |
Конфигурация model-guide в репозитории перечисляет те же отображаемые цифры ToAPIs и связанные строки кредитов: 16 кредитов/секунду при 720p и 20 кредитов/секунду при 1080p. Считайте всё это снимком, а не контрактом. Не переиспользуйте черновую арифметику вроде «1000 клипов за $380».
- Сначала черновите в
720p. Держите duration консервативным (документированное значение по умолчанию — 5 секунд), версионируйте шаблон промпта и меняйте по одной переменной за раз. - Отображаемая цена — не гарантия канала. Прежде чем прогнозировать пакет, подтвердите ID и доступность через
GET /v1/models?type=videoи живую котировку в аккаунте. - Контролируйте расходы на уровне оркестрации: сохраняйте каждый идентификатор задачи, не отправляйте повторно после таймаута клиента, пока не проверите статус, и скачивайте результаты до
expires_at. Официальные контракты поставщиков часто добавляют обязательства или пороги предоплаты; тарификация ToAPIs обычно идёт по факту использования — подтверждайте действующие условия в аккаунте.
6. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: отправляйте kling-3.0-turbo, а не kling-3-turbo; duration — 3–15 секунд; ввод изображения — только первый кадр; документированного контракта звука Turbo или списков Omni нет; опрашивайте путь статуса generations, сохраняйте каждый идентификатор задачи и не выдумывайте SLA.
7. Чек-лист действий
- Создайте ключ на портале разработчика ToAPIs.
- Подтвердите, что
kling-3.0-turboвиден для вашего ключа черезGET /v1/models?type=video— не отправляйтеkling-3-turbo. - Прогоните дымовой тест фрагмента cURL с
resolution: "720p",duration: 5иaspect_ratio: "16:9". - Опрашивайте
GET /v1/videos/generations/{id}с ограниченным дедлайном и скачайте результат доexpires_at. - Далее: углублённый разбор Kling 3.0 Omni, если нужны официальные ссылки Omni или конечный кадр, model guide kling-3.0-turbo для состояния живого каталога и руководство Kling V4 Flash, если нужен другой контракт Kling.







