KovAPIKovAPI
POST https://kovapi.com/v1/images/generations

Режим длинных изображений Kling Image 4.0 от Kuaishou (Beta): целая карточка товара или дизайн веб-страницы одним высоким изображением. 1K / 2K, оригинальный PNG с учётными данными контента C2PA, оплата по типу страницы, длине и разрешению.

Попробовать в песочнице →

Быстрый старт

Асинхронное задание, как и другие вызовы изображений: отправили, получили id задания, опрашиваете результат. Для карточки товара нужны 1–3 фото; веб-страница может быть только по тексту.

Шаг 1: отправьте карточку товара (skill, length, resolution и фото товара)

curl
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "Карточка товара для термокружки с изображения 1: главный визуал, три преимущества, сценарий использования, тексты на русском; используй только то, что видно на фото, не придумывай характеристики", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'

Ответ (HTTP 202)

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}

Шаг 2 · Опрашивайте каждые 2–3 секунды, пока status не станет succeeded или failed

curl
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ при успехе

JSON
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}

Шаг 3: скачайте data[0].url — оригинальный длинный PNG от Kling (ширина 1024 / 2048 px, высота зависит от содержимого), хранится 7 дней.

Полный пример (Python: отправить, дождаться, сохранить на диск)

Python
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Веб-страница: изображения не обязательны
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "Главная страница для обжарщика кофе Northbound Coffee: главное изображение и заголовок, три фирменных сорта, история бренда, подвал, тексты на русском, тёплый минималистичный стиль",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Аутентификация

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Чтобы начать, создайте API-ключ в консоли.

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

JSON-тело запроса POST /v1/images/generations:

ПараметрТипОбязательныйОписание
modelstringДаID модели: kling-image-4.0-long.
promptstringДаЧто нарисовать. Для изображения из изображения опишите, что нужно изменить.
skillstringНетТип страницы: ecommerce (карточка товара; 1–3 фото в images) или webpage (дизайн веб-страницы). Если не указан: ecommerce при наличии изображений, иначе webpage.
lengthstringНетДлина карточки товара: short (примерно 2–5 блоков), medium (по умолчанию, примерно 6–10), long (примерно 11–18); для веб-страницы не указывайте.
resolutionstringНет1K (по умолчанию, ширина 1024 px) или 2K (ширина 2048 px); 4K нет.
image / imagesstring / arrayНетКарточка товара: 1–3 фото товара (обязательно). Веб-страница: до 2; по умолчанию первое — референс объекта, второе — референс стиля. jpg / png, не меньше 300 px по стороне, соотношение 2:5–5:2; каждое стоит на $0.003 больше.
image_rolesarrayНетТолько для веб-страницы: по одному на изображение из images, subject или style, не больше одного каждого, например ["style", "subject"].
nintegerНетОдно длинное изображение за запрос: n должно быть 1.
callback_urlstringНетКуда отправить результат, когда задача завершится; подробнее — в разделе о вебхуках ниже.

Цена

Оплата за изображение по типу страницы, длине и разрешению; каждый референс стоит на $0.003 больше. Резервируется при отправке и полностью возвращается при неудаче.

Тип1K · Кредитов за изображение1K · USD за изображение2K · Кредитов за изображение2K · USD за изображение
Карточка товара · короткая47$0.23556$0.28
Карточка товара · средняя94$0.47109$0.545
Карточка товара · длинная156$0.78172$0.86
Веб-страница109$0.545119$0.595

Размер и формат

  • Ширина фиксирована: 1024 px в 1K, 2048 px в 2K; высота зависит от содержимого (4 257–16 270 px по замерам 11-20).
  • Оригинальный PNG с учётными данными контента C2PA, без обрезки и масштабирования; длинное изображение 2K может весить десятки МБ.
  • Одно готовое длинное изображение за запрос; HTML и редактируемые файлы дизайна не возвращаются.

Как писать промпт

  • Опишите назначение, язык, порядок блоков, преимущества и тексты. Пишите промпт на языке текстов и прямо укажите это, например «тексты на русском».
  • Давайте только реальные данные о товаре и добавьте «используй только предоставленные данные, не придумывай характеристики»: модель пишет то, что вы дали, и может добавить детали от себя.
  • Называйте изображения в промпте @image1, @image2.

Статус задачи и поля ответа

GET /v1/images/jobs/{id} возвращает эти статусы; все поля описаны в разделе Асинхронные задачи. Опрашивайте каждые 2–3 секунды или используйте вебхук.

СтатусЧто значит
queuedВ очереди. В ответе есть queue_position (сколько задач впереди) и eta_seconds (ожидаемое время ожидания).
processingГенерируется.
succeededГотово. Результат в data[0].url, детали оплаты в usage.
failedОшибка. Причина в error; зарезервированные кредиты возвращаются полностью.

Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на изображения — 7 дней.

Сколько ждать

Замеры 11-20: около 1,5–2,5 минуты в 1K и 2,5 в 2K; длинные страницы дольше, в часы пик — ещё дольше.

Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе Коды ошибок.

Ошибки при отправке

HTTPcodeПричинаЧто делать
400missing_promptВ запросе к /v1/images/generations нет prompt.Добавьте prompt.
400invalid_requestНе удаётся прочитать референсное изображение (битая ссылка, не изображение, больше 16MB…; в message указано, какое и почему), в /v1/images/edits нет референсного изображения, тело запроса — не JSON-объект или n — не целое число.Исправьте то, что указано в message, и отправьте снова.
400unsupported_resolutionМодель не поддерживает выбранный уровень разрешения (например, у генерации изображений Grok нет 4K).Выберите другой уровень; доступные уровни указаны в документации каждой модели.
400model_not_foundID модели написан с ошибкой, model не передан или модель нельзя использовать на этом эндпоинте (например, чат-модель на эндпоинте изображений).Берите ID модели из GET /v1/models или из справочника API.
401invalid_api_keyКлюч не существует, удалён или отключён, либо отключён аккаунт.Проверьте ключ на странице API Keys в консоли.
402insufficient_quotaБаланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов.Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс.
429rate_limit_exceededПревышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка Retry-After нет.Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли.
503model_maintenanceМодель на обслуживании и не принимает запросы; пока идёт обслуживание, другая модель вместо неё не ответит.Повторите, когда обслуживание закончится; ход работ — на странице статуса.
503service_unavailableВременный сбой на нашей стороне, например при сохранении референсного файла; /v1/responses также отвечает 503 с Retry-After, когда временно не может принять запрос.Повторите чуть позже.

Неудачные задачи (status — failed)

codeКогда возникаетЧто делать
moderation_blockedИзображение: система безопасности поставщика модели отклонила промпт или референсное изображение (код может быть и content_policy_violation).Перепишите промпт или замените референс; повторная отправка без изменений обычно снова отклоняется.
upstream_errorЛюбая другая ошибка: автоматические повторы не помогли, задача ждала 15 минут и так и не запустилась, поставщик отказал без объяснения причины и т. п.; что именно произошло, указано в message.Обычно повторная отправка проходит успешно.

Вебхуки вместо опроса

Добавьте при отправке callback_url — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». Документация по вебхукам →

curl · callback_url
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "Главная страница для обжарщика кофе Northbound Coffee: главное изображение и заголовок, три фирменных сорта, история бренда, подвал, тексты на русском, тёплый минималистичный стиль", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'