> ## 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 Image

> Генерация по тексту или с использованием до 10 референсов, а также серий из 2–4 связанных изображений. Обычный режим создаёт 1–9 изображений PNG в 2K / 4K / 8K за запрос.

```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-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "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-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "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_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "`prompt` is required for kling-v4-image",
    "type": "invalid_request_error"
  }
}
```

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

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

**Authorization** `string` *required*

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

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

**model** `string` *required*

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

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

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

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

**prompt** `string` *required*

Обязателен для генерации по тексту, по изображению и для серий. Можно описать как желаемое, так и нежелательное содержимое. Ограничение — 50 000 символов для текста только на английском и 21 000 для текста только на китайском и подобных языках; для смешанного текста лимит рассчитывается пропорционально.

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

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

Поддерживаются JPG / JPEG / PNG / GIF. Каждое изображение: не более 30 MB, ширина и высота не менее 300 px, соотношение сторон от 2:5 до 5:2.

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

В промпте можно использовать `@Image1`, `@Image2` и т. д. по порядку изображений в массиве. Без этих меток изображения также учитываются как референсы.

**n** `integer` (default: 1)

Число результатов в обычном режиме: целое от 1 до 9, по умолчанию 1. В режиме серии можно не передавать `n` или указать `1`; число результатов задаёт `sequential_image_generation_options.max_images`. Значение `n > 1` в серии приводит к HTTP 400.

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

Поддерживаются `2K` (по умолчанию), `4K` и `8K` без учёта регистра. Формат результата — PNG. При `1:1` размер 2K — `2048×2048`, 4K — `4096×4096`, 8K — `8192×8192`. Для других пропорций ориентируйтесь на фактические размеры полученных изображений.

В 8K доступны генерация по тексту, по изображениям и создание серий: 1–9 результатов в обычном режиме, 2–4 в серии и до 10 референсов. Требования к формату, размерам и ограничение 30 MB на каждый референс не меняются.

**size** `string` (default: auto)

Соотношение сторон результата. Поддерживаются `auto` (по умолчанию) и следующие 8 значений:

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`.

`auto` выбирает пропорции по промпту или референсам. Размеры в пикселях, например `2048x2048`, не поддерживаются.

**aspect\_ratio** `string`

Псевдоним `size` с теми же значениями. Если переданы оба поля, приоритет имеет `aspect_ratio`.

**sequential\_image\_generation** `string` (default: disabled)

`disabled` или отсутствие поля означает обычную генерацию. `auto` включает серию связанных изображений и требует `sequential_image_generation_options.max_images`. Здесь `auto` не означает автоматический выбор числа изображений.

**sequential\_image\_generation\_options** `object`

Задаёт количество изображений в режиме серии.

**Свойства**

**max\_images** `integer`

Обязателен для серии: целое число от 2 до 4, задающее количество результатов. Отсутствие значения, строка `"auto"` или значение вне диапазона приводит к HTTP 400.

> [!WARNING]
>
> `width`, `height`, `mask_url`, размер `size` в пикселях и `watermark: true` не поддерживаются и приводят к HTTP 400.

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

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

### Генерация по изображению

```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-image",
  "prompt": "Use the dog in @Image1 as a reference for a 3D animated character poster, preserving its fur color and features",
  "image_urls": [
    "https://example.com/dog.png"
  ],
  "size": "3:4",
  "resolution": "2K"
}'
```

### Создать три изображения 4K

```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-image",
  "prompt": "A quiet mountain lake at sunrise, detailed landscape photography",
  "size": "16:9",
  "resolution": "4K",
  "n": 3
}'
```

### Создать одно изображение 8K

```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-image",
  "prompt": "A sweeping aerial view of a misty mountain valley at sunrise",
  "resolution": "8K",
  "size": "16:9",
  "n": 1
}'
```

### Создать серию из четырёх связанных изображений 8K

Укажите `max_images` от 2 до 4. В серии `n` можно не передавать или задать `1`, но значение не может превышать `1`. Создание серии может занять несколько минут; сохраните `task_id` и проверяйте состояние, не отправляя повторный запрос.

```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-image",
  "prompt": "The same tree in spring, summer, autumn, and winter, consistent picture-book style",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 4
  },
  "size": "3:4",
  "resolution": "8K"
}'
```

## Примеры результатов 8K и времени обработки

Ниже приведены замеры в тестовой среде. Размеры изображений и файлов, а также время обработки указаны для примера; фактические результаты могут отличаться.

| Запрос 8K | Размер изображения | Размер файла на изображение | Время до завершения |
| - | - | - | - |
| 1 изображение в обычном режиме (16:9) | `10880×6144` | 117 MB | Около 2,5 минуты |
| 4 / 9 изображений в обычном режиме (1:1) | `8192×8192` | 100–130 MB | Около 3 минут |
| Серия из 4 изображений (3:4) | `7040×9344` | 77–104 MB | Около 6 минут |

Проверяйте статус каждые 5–10 секунд до `completed` или `failed`. Значение `estimated_time` всегда равно 60 секундам и не подходит для прогноза завершения или обратного отсчёта. Сохраните `task_id` и не отправляйте повторный запрос во время ожидания.

Результаты 8K — оригинальные PNG, и один файл может превышать 100 MB. Для списков и предпросмотра используйте самостоятельно созданные миниатюры или загрузку по требованию. Предусмотрите скачивание оригинала и укажите большой размер файла.

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

Читайте `data.status` через [API проверки задач](https://docs.apimart.ai/ru/api-reference/tasks/status.md): `pending` / `processing` — обработка, `completed` — успех, `failed` — ошибка с описанием в `data.error.message`.

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

Ниже показана структура успешного результата. URL находятся в `data.result.images[].url[]`; `url` является массивом. Переберите все результаты и своевременно скачайте их.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_image",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-image.png"
          ]
        }
      ]
    }
  }
}
```

## Оплата

Стоимость зависит от фактического количества созданных изображений и выбранного разрешения. Референсы оплачиваются отдельно за каждое изображение. Тарифы приведены на [странице цен](https://apimart.ai/pricing).

| Объект оплаты | Ключ тарифа |
| - | - |
| Каждое выходное изображение 2K | `kling-v4-image@2K` |
| Каждое выходное изображение 4K | `kling-v4-image@4K` |
| Каждое выходное изображение 8K | `kling-v4-image@8K` |
| Каждое входное изображение-референс | `kling-v4-image@input` |

* В обычном режиме `n=3` оплачивается как 3 результата; для серии учитывается фактически возвращённое количество.
* Каждый референс учитывается один раз за запрос, без умножения на число результатов. При создании 3 изображений по 2 референсам оплачиваются 2 входа и 3 результата.
* Неудачные задачи генерации не оплачиваются; предварительно списанная плата за генерацию возвращается полностью.

## Частые ошибки параметров

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

| Фрагмент ошибки | Решение |
| - | - |
| `` `prompt` is required for kling-v4-image `` | Укажите непустой промпт. |
| `` `n` must be an integer between 1 and 9 `` | Для `n` используйте целое число от 1 до 9. |
| `` `n` cannot be combined with sequential_image_generation=auto `` | В серии не передавайте `n` или задайте `1`; число результатов укажите в `max_images`. |
| `` `sequential_image_generation_options.max_images` is required for kling-v4-image series mode `` | Для серии обязательно укажите `max_images`. |
| `` `sequential_image_generation_options.max_images` must be an integer between 2 and 4 `` | Используйте целое от 2 до 4, а не `"auto"`. |
| `` `resolution` must be 2K, 4K or 8K for kling-v4-image `` | Используйте `2K`, `4K` или `8K`; регистр не учитывается. |
| `` `size` must be auto or one of 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 `` | Используйте `auto` или допустимые пропорции, а не размер в пикселях. |
| `kling-v4-image supports at most 10 reference images` | Передайте не более 10 референсов. |
| `reference image is not accessible for kling-v4-image` | URL референса вернул 403 / 404 / 410. Проверьте публичную доступность и срок действия ссылки или загрузите изображение заново. |
| `unsupported reference image dimensions for kling-v4-image` | Ширина и высота должны быть не менее 300 px, пропорции — от 2:5 до 5:2. Ошибки пропорций используют тот же префикс. |
| `reference image too large for kling-v4-image` | Каждый референс должен быть не более 30 MB. Сожмите его перед повторной отправкой. |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | Используйте целое число JSON, например `"n": 3`, а не строку `"3"`. Другие поля также должны соответствовать заявленному типу: строка, массив или логическое значение. |


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