API Kling Image 4.0 Long Image для e-commerce и веб-страниц

Генерируйте длинные карточки e-commerce и веб-макеты 1K и 2K через API Kling Image 4.0 Long Image: схемы двух режимов, тарифные уровни и таймауты.

Читать в Markdown

Стандартные API генерации изображений перестают справляться, как только вам нужна полноценная прокручиваемая карточка товара e-commerce или макет лендинга из нескольких секций. Пропорции упираются в 9:16 или 21:9, типографика разъезжается между фрагментами, а ручная склейка отдельных баннеров оставляет заметные швы. Kling Image 4.0 Long Image (kling-image-4-0-long-image) решает именно эту задачу, рендеря весь вертикальный макет единым длинным PNG за один вызов POST /v1/images/generations.

В отличие от Kling Image 4.0, которая выдаёт отдельные кадры 2K или 4K и многокадровые серии, эндпоинт Long Image построен вокруг двух специализированных режимов вёрстки — ecommerce и webpage — со своими типами референсов, настройками длины и ступенчатыми тарифами. На конец ноября 2026 года большинство результатов поиска по-прежнему путают эту модель с видео-моделями Kling или обычными апскейлерами. В этом руководстве собраны проверенный контракт API, все тарифные уровни, реальные правила валидации и инженерные нюансы продакшена для многоминутных рендеров и PNG-файлов тяжелее 50 МБ.

Два режима, два строгих контракта ввода

Каждый запрос к kling-image-4-0-long-image обязан указывать settings.skill как ecommerce или webpage. Смешивание типов референсов между двумя режимами возвращает ошибку валидации HTTP 400 ещё до списания.

Поле / правилоskill: "ecommerce"skill: "webpage"
Основной результатВертикальная карточка товара (PDP)Полный прокручиваемый визуальный веб-макет
Типы элементов референсовrefer_image (обязательно: от 1 до 3 фото)style_refer_image (0–1) и subject_refer_image (0–1)
Текстовые вызовы без референсовОтклоняются (HTTP 400)Разрешены
settings.lengthshort (~2–5 секций), medium (по умолчанию, ~6–10), long (~11–18)Игнорируется (не указывать)
settings.resolution1k (ширина 1024 px, по умолчанию) или 2k (2048 px)1k (ширина 1024 px, по умолчанию) или 2k (2048 px)
Разрешение 4kНе поддерживается (HTTP 400)Не поддерживается (HTTP 400)
Число выходовВсегда 1 длинный PNG (output.data[0].url)Всегда 1 длинный PNG (output.data[0].url)

Каждый URL референса должен вести на публично доступный по HTTP(S) файл JPEG или PNG размером до 30 МБ, не менее 300 пикселей по каждой стороне и с соотношением ширины к высоте от 2:5 до 5:2. Учтите, что референсы типа element в kling-image-4-0-long-image не поддерживаются.

Объём промпта заметно больше, чем у обычных генераторов изображений: до 166 000 английских или 71 000 неанглийских символов (для смешанных промптов действует english / 166000 + non_english / 71000 <= 1). Такой запас нужен, чтобы вы могли передать полный текст по секциям, проверенные таблицы характеристик, состав и подписи выносок, не заставляя модель выдумывать свойства товара.

Живые тарифные уровни и математика референсов

Каждая завершённая задача Long Image списывает одну фиксированную ставку уровня — по сочетанию skill, resolution и (для ecommerce) length — плюс сбор за каждое входное референсное фото начиная с первого. Ошибочные и невалидные запросы бесплатны.

Сколько стоит Kling Image 4.0 Long Image

КатегорияЦены (USD)
Ecommerce · 1K · short$0.2269
Ecommerce · 2K · short$0.2723
Ecommerce · 1K · medium$0.4538
Ecommerce · 2K · medium$0.5294
Ecommerce · 1K · long$0.7563
Ecommerce · 2K · long$0.8319
Webpage · 1K$0.5294
Webpage · 2K$0.5748
Референсное изображение$0.003025

На https://api.toklab.ai/v1/pricing (проверено 20 ноября 2026 года) восемь выходных уровней выглядят так, а каждое входное референсное изображение добавляет $0.003025:

Режим (skill)ДлинаРазрешениеТариф выходаПример с 2 референсами
ecommerceshort (~2–5 секций)1k$0.2269$0.23295
ecommerceshort (~2–5 секций)2k$0.2723$0.27835
ecommercemedium (~6–10 секций)1k$0.4538$0.45985
ecommercemedium (~6–10 секций)2k$0.5294$0.53545
ecommercelong (~11–18 секций)1k$0.7563$0.76235
ecommercelong (~11–18 секций)2k$0.8319$0.83795
webpageн/д1k$0.5294$0.53545
webpageн/д2k$0.5748$0.58085

Присмотритесь к переходу с 1K на 2K: апгрейд с 1k до 2k добавляет всего $0.0454 в webpage (+8,6%) и $0.0756 в ecommerce medium или long (+10% до +16,7%). Поскольку длинные страницы содержат мелкие UI-подписи, таблицы характеристик и наборный текст, для финальных материалов почти всегда стоит брать 2k (ширина 2048 px), а 1k оставлять для недорогих структурных черновиков до утверждения плана секций.

Пример карточки товара e-commerce Kling Image 4.0 Long Image, сгенерированный в TokLab

Структура промпта для режимов ecommerce и webpage

Так как модель собирает всю прокручиваемую страницу за один проход, расплывчатые промпты приводят к повторяющимся шаблонным блокам или выдуманным характеристикам. Если писать промпт как спецификацию вайрфрейма, макеты получаются заметно чище:

  1. Перечислите секции в точном порядке сверху вниз. Явно пронумеруйте каждую полосу — например: Section 1: Hero banner, Section 2: 3-column feature callouts, Section 3: Macro texture detail, Section 4: Specification table, Section 5: Care instructions and footer.
  2. Привяжите каждое фото референса через @id. В режиме ecommerce дайте понятные ID (front, spout, box) и укажите, в какой секции использовать каждый ракурс. В режиме webpage отделите визуальный стиль (@layout через style_refer_image) от главного объекта (@product через subject_refer_image).
  3. Укажите точные тексты и цифры. Никогда не пишите «добавь реалистичные технические характеристики». Передайте точные ватты, габариты, материалы и заголовки, чтобы потом не исправлять выдуманные значения.
  4. Согласуйте settings.length с числом секций. Запрос 14 подробных блоков внутри length: "short" сожмёт типографику так, что мелкие подписи станут нечитаемыми. Соотносите 2–5 блоков с short, 6–10 с medium и 11–18 с long.

Выбор подходящего уровня длины для e-commerce

Выбор между short, medium и long одновременно влияет на визуальный ритм и на бюджет. Страница short (~2–5 секций, $0.2269 в 1k или $0.2723 в 2k) подходит для промо-карточек одного SKU, мобильных тизеров на маркетплейсах и сравнительных полос, где покупателю достаточно hero-кадра, трёх преимуществ и одного компактного блока характеристик. Страница medium (~6–10 секций, $0.4538 в 1k или $0.5294 в 2k) — практическая золотая середина для большинства карточек Shopify, Amazon A+ и трансграничных витрин: хватает вертикального пространства для hero-визуала, макро-кадров материалов, сценариев использования, таблицы габаритов и комплектации без воды.

Оставляйте long (~11–18 секций, $0.7563 в 1k или $0.8319 в 2k) для флагманской электроники, бытовой техники или наборов с несколькими вариантами, где действительно нужны сюжетные блоки, схемы узлов в разрезе, пошаговые инструкции, знаки сертификации и блоки FAQ. Если реальных фактов о товаре не хватает на одиннадцать и более секций, режим long начинает повторять прежние ракурсы или выдумывать общие лайфстайл-баннеры, тратя впустую и время рендера, и бюджет.

Зачем режим webpage разделяет референсы стиля и объекта

В режиме webpage разделение style_refer_image и subject_refer_image снимает классическую проблему API с общим списком референсов: модель либо копирует в ваш макет чужой товар, либо переносит загромождённый фон вашего фото товара в интерфейс сайта. Передача редакционного скриншота или фрейма Figma в style_refer_image ограничивает его ритмом сетки, цветовыми токенами, типографической иерархией и стилем кнопок, а чистое студийное фото в subject_refer_image сохраняет точный облик физического продукта в hero-блоке и карточках преимуществ. Если нужен оригинальный арт-дирекшн только по тексту, не передавайте оба поля и опишите палитру, шрифтовую пару и сетку прямо в промпте.

Проверка качества перед публикацией сгенерированных страниц

Даже в разрешении 2k готовые длинные изображения должны проходить быстрый автоматический и визуальный QA-контроль перед публикацией на витрине или в презентации клиенту. Во-первых, сверьте каждую цифру, единицу измерения и строку состава с исходным промптом — мелкие опечатки в плотных таблицах характеристик гораздо проще заметить при масштабе 100%, чем на уменьшенном превью. Во-вторых, убедитесь, что физическая геометрия продукта (расположение кнопок, логотипов, разъёмов и пропорции) не поплыла от hero-блока до крупных планов. В-третьих, проверьте вертикальную читаемость на мобильном экране шириной 390 px после нарезки: плотный десктопный ряд из 4 колонок, чёткий при ширине 2 048 px, может стать нечитаемым на телефоне, если заранее не запросить контрастные 2-колоночные или вертикальные мобильные карточки.

Полные примеры запросов для обоих режимов

1. Карточка товара e-commerce (medium, 2k)

{
  "model": "kling-image-4-0-long-image",
  "contents": [
    {"type": "refer_image", "url": "https://example.com/kettle-front.png", "id": "front"},
    {"type": "refer_image", "url": "https://example.com/kettle-spout.jpg", "id": "spout"},
    {
      "type": "prompt",
      "text": "Design a clean ecommerce product detail page for the matte black gooseneck kettle in @front. Section 1: Hero banner with headline 'Precision Pour 0.9L' and @front centered on warm stone. Section 2: Three feature cards covering 1200W rapid boil, 1-degree PID control, and 60-minute hold. Section 3: Macro close-up based on @spout highlighting laminar flow control. Section 4: Lifestyle pour-over brewing scene. Section 5: Dimension and electrical spec table (900 ml, 1200W, 120V, 304 stainless steel). Section 6: Box contents and care notes."
    }
  ],
  "settings": {
    "skill": "ecommerce",
    "length": "medium",
    "resolution": "2k"
  }
}

2. Визуальный веб-макет с референсами стиля и объекта (2k)

import os
import time
import requests

API_KEY = os.environ["TOKLAB_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-image-4-0-long-image",
    "contents": [
        {"type": "style_refer_image", "url": "https://example.com/editorial-grid.png", "id": "grid"},
        {"type": "subject_refer_image", "url": "https://example.com/chronograph.jpg", "id": "watch"},
        {
            "type": "prompt",
            "text": (
                "Create a vertical product launch webpage adopting the Swiss editorial grid, "
                "high-contrast serif headings, and generous whitespace of @grid while featuring @watch. "
                "Include: top navigation bar, full-bleed hero with @watch, three-card movement breakdown, "
                "water-resistance specification band, and minimalist footer."
            ),
        },
    ],
    "settings": {"skill": "webpage", "resolution": "2k"},
}

resp = requests.post(
    "https://api.toklab.ai/v1/images/generations",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["id"]

# Poll every 5s; long 2K layouts can take several minutes.
deadline = time.time() + 600
while time.time() < deadline:
    status_resp = requests.get(
        f"https://api.toklab.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_resp.raise_for_status()
    data = status_resp.json()
    if data.get("status") == "completed":
        png_url = data["output"]["data"][0]["url"]
        print("Ready:", png_url)
        break
    if data.get("status") == "failed":
        raise RuntimeError(f"Long image task failed: {data}")
    time.sleep(5)

Инженерные заметки для продакшена: таймауты, PNG тяжелее 50 МБ и нарезка

Интеграция kling-image-4-0-long-image в бэкенд-сервис отличается от работы с быстрым генератором 1024×1024 тремя эксплуатационными моментами:

  • Закладывайте многоминутную задержку задачи. Рендер e-commerce в режиме long + 2k регулярно занимает несколько минут. Не держите открытым HTTP-запрос из браузера или serverless-функции с 30-секундным таймаутом — ставьте ID задачи в фоновый воркер и опрашивайте GET /v1/tasks/:id с потолком в 10 минут.
  • Скачивайте крупные PNG потоково. Поскольку длинное изображение 2k имеет ширину 2 048 пикселей и может достигать 10 000–20 000+ пикселей по высоте, итоговый PNG способен превышать 50 МБ. Используйте потоковую загрузку (requests.get(url, stream=True)) с щедрыми таймаутами чтения и не буферизуйте несколько сырых растров в памяти небольшого контейнера.
  • Нарезайте и перекодируйте для живых витрин. Маркетплейсы (Shopify, Amazon A+, Taobao/Tmall) и мобильные браузеры плохо относятся к одиночным PNG на 50 МБ. После проверки готового макета разрежьте мастер-PNG по границам секций и пересохраните каждый фрагмент в WebP или прогрессивный JPEG с качеством 80–85% для быстрой загрузки витрины.

Частые ошибки HTTP 400, от которых стоит защититься

Проверяйте эти пять условий перед вызовом эндпоинта:

  1. Отсутствует settings.skill (должно быть "ecommerce" или "webpage").
  2. skill: "ecommerce" с нулём или более чем тремя элементами refer_image.
  3. Передача refer_image в режиме webpage либо style_refer_image / subject_refer_image в режиме ecommerce.
  4. Запрос resolution: "4k" (для Long Image существуют только "1k" и "2k").
  5. Повторное использование одного и того же id у двух референсов в contents.

Если вашему процессу нужны стандартные горизонтальные или квадратные кадры для кампаний, лайфстайл-сеты товаров или до 10 референсов в одном кадре, направляйте такие задачи в Kling Image 4.0, а Kling Image 4.0 Long Image оставляйте для вертикальных многосекционных страниц.

Источники

Похожие руководства