> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Генерация длинных изображений Kling V4 Long Image

> Создание длинных изображений страниц товаров и дизайна веб-страниц в 1K / 2K. Поддержка short / medium / long для товаров и референсов товара, стиля и объекта. Один PNG за запрос.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": True
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_kling_v4_long_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

Отправьте асинхронный запрос в `POST /v1/images/generations` с `model: "kling-v4-long-image"`. Получите `data[0].task_id`, затем проверьте `GET /v1/tasks/{task_id}`. Каждый запрос возвращает один длинный PNG; режим веб-страницы создаёт изображение её дизайна.

## Выбор режима

| Режим | `skill` | Референсы | Длина |
| - | - | - | - |
| Страница товара | `ecommerce` | `image_urls`: обязательны 1–3 изображения товара | `short` / `medium` / `long` |
| Дизайн веб-страницы | `webpage` | `image_with_roles`: необязательные референсы стиля и объекта, по одному | Не передавать `length` |

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

**Authorization** `string` *required*

Используйте `Authorization: Bearer <token>`, где `<token>` — ваш API-ключ APIMart.

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

**model** `string` *required*

Укажите `kling-v4-long-image`.

**nsfw\_check** `boolean` (default: false)

Выполнять ли проверку содержимого перед отправкой задачи генерации изображения.

* `true`: проверить промпты и входные изображения с помощью `omni-moderation-latest`
* `false` или параметр не указан: не отправлять запрос на проверку, без дополнительных затрат и задержки (по умолчанию)

**prompt** `string` *required*

Обязателен, не может состоять только из пробелов. До 166 000 символов для текста только на английском, до 71 000 для китайского и подобных языков; смешанный текст рассчитывается пропорционально. Опишите макет, разделы, тексты, стиль и объект.

**skill** `string` *required*

Обязателен: `ecommerce` для страницы товара или `webpage` для дизайна веб-страницы, без учёта регистра. Режимы используют разные поля референсов.

**length** `string` (default: medium)

Только для `skill: "ecommerce"`: `short`, `medium` (по умолчанию) или `long`, примерно 2–5, 6–10 или 11–18 разделов. Фактическое содержание и высота зависят от результата. В режиме веб-страницы поле нужно опустить, иначе HTTP 400.

**resolution** `string` (default: 1K)

Поддерживаются `1K` (по умолчанию) и `2K` без учёта регистра. Для товара оба разрешения доступны при любой длине, включая `long + 2K`. Ширина результата — 1024 и 2048 px соответственно, высота зависит от содержания. `4K` не поддерживается.

**image\_urls** `string[]`

Только для страницы товара: обязательны 1–3 изображения. В режиме веб-страницы опустите поле и используйте `image_with_roles`. Нужны общедоступные прямые URL. Локальные файлы можно загрузить через [API загрузки изображений](https://docs.apimart.ai/ru/api-reference/uploads/images.md) и передать полученный `url`.

**image\_with\_roles** `object[]`

Необязательно, только для веб-страниц. Не более одного изображения `style` и одного `subject`; можно опустить одну или обе роли. В режиме товара поле нужно опустить.

**Элемент массива**

**url** `string` *required*

Общедоступный прямой URL изображения-референса.

**role** `string` *required*

`style` задаёт визуальный стиль и макет; `subject` — объект, который нужно сохранить. Каждая роль допустима только один раз.

**n** `integer`

Каждый запрос создаёт одно длинное изображение. Опустите поле или передайте целое `1`; другие значения приводят к HTTP 400.

**watermark** `boolean`

Опустите поле или передайте `false`; `true` приводит к HTTP 400.

> [!WARNING]
>
> Не передавайте `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation` и `sequential_image_generation_options`. Даже `null` или пустая строка в этих полях приводит к HTTP 400.

## Требования к референсам и их обозначения

Поддерживаются JPG / JPEG / PNG. Каждый файл — до 30 MB, обе стороны не менее 300 px, пропорции от 2:5 до 5:2. Ответ URL HTTP 403 / 404 / 410, неподходящие размеры или пропорции, превышение размера файла синхронно возвращают HTTP 400 без создания задачи и платы за генерацию. Другие ошибки загрузки, например тайм-аут исходного сервера, сначала принимаются; затем задача завершается ошибкой с возвратом предоплаты.

Используйте в промпте `@Image1`, `@Image2` и т. д. Для товаров порядок соответствует `image_urls`; для веб-страницы сначала идёт стиль, затем объект. Если передана одна роль, её изображение — `@Image1`.

## Примеры запросов

Отправляйте запросы в `POST /v1/images/generations`. Замените примерные URL доступными прямыми ссылками.

### Длинная страница товара в 2K

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### Веб-страница с референсами стиля и объекта

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### Веб-страница только по промпту

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## Проверка задачи

Опрос [API задач](https://docs.apimart.ai/ru/api-reference/tasks/status.md) рекомендуется выполнять раз в 10 секунд. Сохраните `task_id` и не дублируйте запрос генерации при долгом ожидании.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_kling_v4_long_image' \
  --header 'Authorization: Bearer <token>'
```

| Состояние (`data.status`) | Действие |
| - | - |
| `pending` / `processing` | Продолжайте опрос. `data.cost` — предварительно списанная сумма, `data.billing_status` — `held`. |
| `completed` | Читайте `data.result.images[0].url[0]`. `data.billing_status` — `settled`, `data.cost` — итоговая плата. |
| `failed` | Читайте `data.error.message`. `data.billing_status` — `refunded`, `data.cost` — `0`; предоплата полностью возвращается. |

Ниже показана структура успешного результата. `images` и `url` — массивы; модель возвращает одно длинное изображение за запрос.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

Скачайте изображение до Unix-времени в секундах из `data.result.images[0].expires_at`. После этого ссылка истекает.

> [!NOTE]
>
> Генерация обычно занимает несколько минут; один пример `long + 2K` потребовал 432 секунды. `estimated_time` сейчас всегда равен 60 секундам и не подходит для обратного отсчёта или порога тайм-аута. Время зависит от содержания и нагрузки; замер не является верхним пределом.
>
> Высота и размер файла зависят от содержания. Один пример `long + 2K` имел `2048×46615` пикселей и 63,9 MB; это не ограничения вывода. Результат может превышать 50 MB — учитывайте затраты на загрузку и отображение больших изображений.

## Оплата

За запрос оплачивается одно длинное изображение по выбранному тарифу плюс референсы: **цена выходного тарифа + число референсов × цена референса**. Учитываются товар, стиль и объект; первый референс также платный.

Ниже перечислены 8 выходных тарифов. Ключи цен: `kling-v4-long-image@<тариф>` и `kling-v4-long-image@input` для референсов. В запросе генерации `resolution` по-прежнему принимает только `1K` или `2K`.

| Режим | Длина | `1K` | `2K` |
| - | - | - | - |
| Страница товара | `short` | `1K-SHORT` | `2K-SHORT` |
| Страница товара | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Страница товара | `long` | `1K-LONG` | `2K-LONG` |
| Дизайн веб-страницы | Не передавать `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

При отправке сумма списывается предварительно, при успехе расчёт завершается, при ошибке предоплата возвращается полностью. Цены и скидки аккаунта указаны на [странице цен](https://apimart.ai/pricing).

## Частые ошибки

Эти ошибки проверки синхронно возвращают HTTP 400 без создания задачи и платы за генерацию. Ошибки отправки — в `error.message`, ошибки после создания — в `data.error.message`.

| Фрагмент ошибки | Решение |
| - | - |
| `` `prompt` is required for kling-v4-long-image `` | Укажите непустой промпт. |
| `` `skill` is required for kling-v4-long-image `` | Передайте `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Используйте `ecommerce` или `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Требуются 1–3 изображения товара. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Не более 3 изображений товара. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | Для товара используйте `image_urls`, опустите `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Длина — `short`, `medium` или `long`. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Для веб-страницы опустите `length`. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | Для веб-страницы опустите `image_urls`, используйте `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Допустимы только `style` и `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | Не более одного изображения на роль; повтор объекта тоже запрещён. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Используйте `1K` или `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Удалите неподдерживаемые поля размеров, пропорций или серий; не передавайте `null` и пустые строки. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Опустите `n` или передайте целое `1`. |
| `reference image is not accessible for kling-v4-long-image` | Проверьте публичность, срок действия URL и ответы 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Обе стороны не менее 300 px, пропорции от 2:5 до 5:2. |
| `reference image too large for kling-v4-long-image` | Каждый референс — не более 30 MB. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.