how-tos

Руководство по Kling Image 4.0 API: первый запрос на cURL и Python

Poyo.ai Team
9 min read
Share:

Руководство по Kling Image 4.0 API: первый запрос на cURL и Python

Это руководство по Kling Image 4.0 API проведёт вас от API-ключа до готового изображения: один вызов cURL, цикл опроса на Python с ограничением по времени, а затем рабочее JSON-тело для каждого режима ввода kling-4.0-image и kling-4.0-long-image. Любой из них можно сначала попробовать в playground Kling Image 4.0; все тела запросов ниже соответствуют документации PoYo.

Первый запрос к Kling Image 4.0 API через cURL

Создайте ключ в панели PoYo и храните его на своём сервере как POYO_API_KEY. Затем отправьте задачу text-to-image в 2K:

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0-image",
    "input": {
      "prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
      "size": "16:9",
      "resolution": "2K"
    }
  }'

В ответе есть code: 200 и data.task_id со status: "not_started". Отправленная задача — ещё не готовое изображение. Проверьте её так:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Статусы: not_started, running, finished и failed. При finished поле data.files содержит по одной записи на изображение с file_url и file_type: "image", а data.credits_amount показывает стоимость задачи. При failed читайте data.error_message.

Цикл опроса на Python с ограничением по времени

Этот код работает на вашем бэкенде с requests. Он проверяет и HTTP-статус, и поле code в теле ответа (ошибки валидации могут прийти как HTTP 200 с code: 400), останавливается на failed и прекращает ожидание через 20 минут без повторной отправки, потому что повторная отправка — это повторный счёт.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(resp):
    resp.raise_for_status()
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
    return body["data"]

def run(payload, max_wait=1200, every=10):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
        time.sleep(every)
    raise TimeoutError("still running, poll task " + task_id + " again later")

urls = run({
    "model": "kling-4.0-image",
    "input": {
        "prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
        "size": "1:1",
        "resolution": "2K",
    },
})
print(urls)

Для долгих задач лучше добавьте в payload на верхнем уровне "callback_url": "https://your-domain.com/poyo-hook". PoYo отправит POST с теми же данными задачи (без обёртки code/data), когда задача завершится или упадёт, с подписью HMAC-SHA256 в X-Webhook-Signature; как её проверить, показано в документации по вебхукам.

Image-to-image с image_urls

Передайте от 1 до 10 публичных HTTP(S) URL в image_urls. Первый — это @Image1, второй — @Image2, в порядке массива. Назначьте каждому роль в промпте и укажите, что должно остаться без изменений.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "resolution": "2K"
  }
}

image_urls должен быть массивом даже для одного изображения. Каждое изображение — не больше 30 MB, не меньше 300 px в ширину и высоту, с соотношением ширины к высоте от 0.4 до 2.5.

Единообразные объекты с kling_elements

Элемент — это один персонаж или объект, показанный с 2–4 ракурсов, фронтальный первым. Элементам нужен хотя бы один URL в image_urls, и передать их можно до 7; изображения плюс элементы ограничены 10.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
    "image_urls": ["https://example.com/living-room.png"],
    "kling_elements": [
      {
        "element_input_urls": [
          "https://example.com/character-front.png",
          "https://example.com/character-side.png",
          "https://example.com/character-back.png"
        ]
      }
    ],
    "resolution": "2K"
  }
}

Этот запрос стоит 13 кредитов за изображение 2K плюс 1 за референсное изображение и 1 за элемент: 15 кредитов ($0.075).

Серии изображений с enable_sequential

При enable_sequential: true значение n от 2 до 10 (по умолчанию 4), и модель планирует изображения как одну серию с теми же объектами и стилем, возвращая их по порядку. Если параметр выключен, n от 1 до 9 возвращает независимые изображения.

{
  "model": "kling-4.0-image",
  "input": {
    "prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
    "size": "3:2",
    "enable_sequential": true,
    "n": 4
  }
}

В нашем тесте в день запуска (продакшен-API PoYo, 19 ноября 2026 года) серия 16:9 в 2K с n: 4 вернула четыре изображения 2720×1536 с тем же мотоциклистом, мотоциклом и одеждой на рассвете, в полдень, на закате и ночью. Серия стоит 52 кредита, от отправки до результата прошло около 4.9 минуты.

Длинные веб-страницы и страницы e-commerce

Смените ID модели на kling-4.0-long-image и выберите skill. Дизайн веб-страницы, при желании по референсу стиля:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
    "skill": "webpage",
    "style_image_url": "https://example.com/style-reference.png",
    "resolution": "2K"
  }
}

Карточка товара для e-commerce по одному фото товара:

{
  "model": "kling-4.0-long-image",
  "input": {
    "prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
    "skill": "ecommerce",
    "image_urls": ["https://example.com/water-bottle.png"],
    "length": "medium",
    "resolution": "1K"
  }
}

Совет: укажите язык страницы. В нашем тесте английский промпт веб-страницы, в котором не было сказано, на каком языке должен быть текст, вернул страницу с китайским текстом. Добавление в промпт "All text on the page is in English." решило проблему, поэтому оба тела выше заканчиваются этой строкой. Наш тест веб-страницы в 1K вернул одно изображение 1024×4257 за 110 кредитов примерно за 1.7–2.2 минуты.

image_urls и length относятся к ecommerce; style_image_url и subject_image_url — к webpage. Подробнее о длине страниц и выводе 8K — в статье 8K и длинные изображения с Kling Image 4.0 API.

Сохранение результатов

Каждый files[].file_url указывает на PNG. Копируйте его в своё хранилище, а не ссылайтесь на него напрямую из приложения. Три момента из нашего прогона в день запуска, к которым стоит подготовиться:

  • Размер. Одно изображение 16:9 в 8K — это PNG 10880×6144 размером около 128 MB. Скачивайте его потоком на диск, а не в память, и увеличьте таймаут чтения клиента.
  • Альфа-канал. Скачанные файлы были PNG в RGBA даже для непрозрачных изображений. Если ваш пайплайн, CDN или процесс печати ожидает RGB или JPEG, конвертируйте после скачивания.
  • Порядок. Серия изображений возвращается по порядку, поэтому индекс в files — это номер кадра вашей раскадровки или слайда.

Правила валидации, которые стоит проверить до отправки

ПравилоМодель
prompt 1–50,000 символов, не только пробелыобе
image_urls 1–10 элементов; каждый 30 MB, ≥300 px, соотношение 0.4–2.5kling-4.0-image
kling_elements ≤ 7, в каждом 2–4 URL, только вместе с image_urls; изображения + элементы ≤ 10kling-4.0-image
n 1–9 без серии, 2–10 с enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" требует 1–3 image_urls; resolution 1K / 2Kkling-4.0-long-image
Никаких лишних полей (output_format, seed, negative_prompt отклоняются)обе

Ошибки, которые стоит обрабатывать

codeЗначениеЧто делать
400Неверные параметрыИсправьте тело; не повторяйте без изменений
401Отсутствует или неверен API-ключПроверьте заголовок
402Недостаточно кредитовПополните баланс и отправьте заново
429Лимит запросовПодождите и повторите позже
500 / 502 / 503Ошибка сервера или вышестоящего провайдераПовторите отправку с backoff

Задача failed не тарифицируется, поэтому повторная отправка после ошибки безопасна. Повторная отправка после таймаута на вашей стороне — нет: сначала опросите тот же task_id.

Как считается ваш первый счёт

kling-4.0-image стоит цену за изображение, умноженную на число изображений, плюс 1 кредит за каждый URL в image_urls и каждый элемент один раз за запрос. При 1 кредит = $0.005:

ЗапросКредитыUSD
Первый вызов cURL выше (2K, одно изображение)13$0.065
Тот же промпт в 8K32$0.16
Правка с элементом выше (2K, 1 изображение + 1 элемент)15$0.075
Серия из четырёх изображений 2K52$0.26
Веб-страница 1K, без референсов110$0.55
Страница e-commerce 1K medium, 1 фото товара95$0.475

Полные таблицы и больше примеров — в статье цены Kling Image 4.0 API. Обзор обоих ID моделей — в статье Что такое Kling Image 4.0.

Часто задаваемые вопросы

Как вызвать Kling Image 4.0 API из Python? Отправьте JSON-тело методом POST на https://api.poyo.ai/api/generate/submit с помощью requests, прочитайте data.task_id, затем опрашивайте /api/generate/status/{task_id} до finished и читайте files[].file_url. Цикл выше делает это с дедлайном и проверкой ошибок.

Какой ID модели у Kling Image 4.0 API? kling-4.0-image для text-to-image, правок и серий изображений и kling-4.0-long-image для длинных веб-страниц и страниц e-commerce. kling-4-0-image — это только слаг страницы.

Поддерживает ли Kling Image 4.0 API вебхуки? Да. Добавьте callback_url на верхнем уровне запроса. PoYo отправит подписанный POST, когда задача завершится или упадёт.

Можно ли получить JPEG из Kling Image 4.0 API? Поля для формата вывода нет; результаты — PNG. Наши скачанные файлы были PNG в RGBA даже для непрозрачных изображений, так что если нужен JPEG, конвертируйте на своей стороне.

Почему моя длинная веб-страница из Kling Image 4.0 пришла на другом языке? Если в промпте не указан язык текста страницы, модель может выбрать его сама. Укажите его, например "All text on the page is in English."

Share: