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

# Long Image Generation

> Source: https://kling.ai/document-api/api/image/4-0/long-image-generation
> Locale: en
> Current Tab: Long Image Generation
> Sibling Tabs: Image Generation / Long Image Generation / Element Management
> This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted.

---

## Create Task

### API Overview

- Method: `POST`
- Path: `/long-image-generation/kling-4.0`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

Generate a long image for an ecommerce product detail page or webpage visual design. The final result is one complete image.

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data exchange format |
| `Authorization` | string | Yes | - | - | Authentication information; see API Authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `contents` | array | Yes | - | - | A collection of reference input materials, such as prompts and images. |
| `contents[].type` | string | Yes | - | `prompt`, `refer_image`, `style_refer_image`, `subject_refer_image` | Input material type. Supports prompts, reference images, style reference images, and subject reference images. Element Library materials (type=element) are not supported as references. |
| `settings` | object | Yes | - | - | Output settings, such as the skill and resolution used to generate the long image. Only one complete long image can be generated per request; specifying the number of output images is not supported. |
| `settings.skill` | string | Yes | - | `ecommerce`, `webpage` | Skill used to generate the long image. |
| `settings.length` | string | No | `medium` | `short`, `medium`, `long` | Length of the generated page: long, medium, or short. Applies only to ecommerce product detail page generation (skill=ecommerce). |
| `settings.resolution` | string | No | `1k` | `1k`, `2k` | Image generation resolution. Applies to both ecommerce product detail pages and webpage designs. |
| `options` | object | No | - | - | General configuration, such as callback URL and whether to include a watermark |
| `options.callback_url` | string | No | - | - | Callback notification URL for this task's results |
| `options.external_task_id` | string | No | - | - | User-defined task ID |
| `options.watermark_info` | object | No | - | - | Whether to generate watermarked results simultaneously |
| `options.watermark_info.enabled` | boolean | No | `false` | - | true enables generation, false disables generation; defaults to false. |

#### Request Body Field Notes

- `contents`: Required and nonempty
- `contents`: The reference format is shown below. See the parameter descriptions below for details:
- `contents`: ```json
  "contents": [
    {
      "type": "prompt",// Prompt input material; required and nonempty
      "text": "string"
    },
    {
      "type": "refer_image",// Reference image input material for ecommerce product detail pages; not supported for webpage design
      "url": "string",
      "id": "string"
    },
    {
      "type": "style_refer_image",// Style reference image input material, used to reference the image's visual and layout styles; not supported for ecommerce product detail page generation
      "url": "string",
      "id": "string"
    },
    {
      "type": "subject_refer_image",// Subject reference image input material, used to preserve the subject shown in the image and create a design around it; not supported for ecommerce product detail page generation
      "url": "string",
      "id": "string"
    }
  ]
  ```
- `contents[].type`: prompt: Prompt input material type.
  - refer_image: Reference image input material type.
  - style_refer_image: Style reference image input material type, used to reference the image's visual and layout styles.
  - subject_refer_image: Subject reference image input material type, used to preserve the subject shown in the image and create a design around it.
- `contents[].type`: Input materials must include a prompt; prompt is required and must not be empty.
- `contents[].type`: For ecommerce product detail page generation (settings.skill=ecommerce), refer_image is required, and 1–3 reference images must be provided;
- `contents[].type.prompt`: Prompts can be templated to meet different image generation needs.
- `contents[].type.prompt`: Prompt length: English-only input must not exceed 166,000 characters; non-English-only input must not exceed 71,000 characters. Mixed input must satisfy: English character count/166000 + non-English character count/71000 ≤ 1.
- `contents[].type.prompt`: Defined in JSON format as follows:
- `contents[].type.prompt`: ```json
  {
    "type": "prompt", // Input material type; fixed parameter value: prompt; required
    "text": "string" // Text prompt content; required
  }
  ```
- `contents[].type.refer_image`: Not supported for webpage design (settings.skill=webpage). To provide reference images, use type=style_refer_image or type=subject_refer_image.
- `contents[].type.refer_image`: Defined in JSON format as follows:
- `contents[].type.refer_image`: ```json
  {
    "type": "refer_image", // Image input material identifier
    "url": "string", // Input material content, provided via url or base64; required
    "id": "string" // Input material index ID, used to reference the material in prompt; this parameter must be unique within the same task
  }
  ```
- `contents[].type.refer_image`: Accepts an image URL or Base64-encoded data. The URL must be accessible, and the value must not be empty.
- `contents[].type.refer_image`: Supported image formats: .jpg/.jpeg/.png.
- `contents[].type.refer_image`: Each image file must not exceed 30 MB. Both width and height must be at least 300 px, and the aspect ratio must be within 2:5–5:2.
- `contents[].type.style_refer_image`: Applies only to webpage design (settings.skill=webpage). Not supported for ecommerce product detail page generation (settings.skill=ecommerce); use type=refer_image to provide reference images.
- `contents[].type.style_refer_image`: Defined in JSON format as follows:
- `contents[].type.style_refer_image`: ```json
  {
    "type": "style_refer_image", // Style reference image input material identifier
    "url": "string", // Input material content, provided via url or base64; required
    "id": "string" // Input material index ID, used to reference the material in prompt; this parameter must be unique within the same task
  }
  ```
- `contents[].type.style_refer_image`: Accepts an image URL or Base64-encoded data. The URL must be accessible, and the value must not be empty.
- `contents[].type.style_refer_image`: Supported image formats: .jpg/.jpeg/.png.
- `contents[].type.style_refer_image`: Each image file must not exceed 30 MB. Both width and height must be at least 300 px, and the aspect ratio must be within 2:5–5:2.
- `contents[].type.subject_refer_image`: Applies only to webpage design (settings.skill=webpage). Not supported for ecommerce product detail page generation (settings.skill=ecommerce); use type=refer_image to provide reference images.
- `contents[].type.subject_refer_image`: Defined in JSON format as follows:
- `contents[].type.subject_refer_image`: ```json
  {
    "type": "subject_refer_image", // Subject reference image input material identifier
    "url": "string", // Input material content, provided via url or base64; required
    "id": "string" // Input material index ID, used to reference the material in prompt; this parameter must be unique within the same task
  }
  ```
- `contents[].type.subject_refer_image`: Accepts an image URL or Base64-encoded data. The URL must be accessible, and the value must not be empty.
- `contents[].type.subject_refer_image`: Supported image formats: .jpg/.jpeg/.png.
- `contents[].type.subject_refer_image`: Each image file must not exceed 30 MB. Both width and height must be at least 300 px, and the aspect ratio must be within 2:5–5:2.
- `settings.skill`: ecommerce: Ecommerce product detail page.
  - webpage: Webpage design.
- `settings.length`: short: Short, approximately 2~5 content sections; (Note: Content sections are content modules or segments within the final long image, not the number of output images. The final result is still one complete long image.)
  - medium: Medium, approximately 6~10 content sections;
  - long: Long, approximately 11~18 content sections;
- `settings.length`: This parameter is not supported for webpage design (skill=webpage) and has no effect if set.
- `settings.resolution`: 1k: 1K standard definition;
  - 2k: 2K high-res;
- `options.callback_url`: If configured, the server proactively sends notifications when the task status changes
- `options.callback_url`: For the notification message schema, see the [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks)
- `options.external_task_id`: Providing this ID does not overwrite the system-generated task ID, but it can be used to query the task
- `options.external_task_id`: Ensure that IDs are unique within a single user account
- `options.watermark_info`: Defined using the enabled parameter:
  ```json
  "watermark_info": {
    "enabled": false // true: generate watermarked result; false: do not generate; default: false
  }
  ```
- `options.watermark_info`: Custom watermarks are not currently supported

### Request Example

```bash
curl --request POST \
  --url "https://api-singapore.klingai.com/long-image-generation/kling-4.0" \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "contents": [
    {
      "type": "prompt",
      "text": "Design a complete ecommerce product detail page as a long image for the coffee machine in @product, including the key visual, core selling points, and usage scenarios; use only the provided product facts and do not fabricate specifications"
    },
    {
      "type": "refer_image",
      "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/Coffee_machine.png",
      "id": "product"
    }
  ],
  "settings": {
    "skill": "ecommerce",
    "length": "medium",
    "resolution": "2k"
  },
  "options": {
    "external_task_id": ""
  }
}'
```

### Response Example

```json
{
  "code": 0, // Error code; 0 indicates success; see the error code documentation for definitions
  "message": "SUCCEED", // API message
  "request_id": "example-long-request-id", // Request tracking ID, generated by the system
  "data": {
    "id": "example-long-task-id", // System task ID, generated by the platform
    "status": "submitted", // Task status: submitted/processing/succeeded/failed
    "create_time": 1790000000000, // Task creation time, Unix timestamp in milliseconds
    "update_time": 1790000000000, // Task update time, Unix timestamp in milliseconds
    "external_id": "string" // User-defined task ID specified at creation (if any)
  }
}
```

## More Scenario Examples

### Webpage design (text-only, 2K; length is not supported)

```cURL
curl --request POST \
  --url "https://api-singapore.klingai.com/long-image-generation/kling-4.0" \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "contents": [
    {
      "type": "prompt",
      "text": "Design a long visual image for a specialty coffee brand website, including the hero section, product showcase, roasting philosophy, store information, and footer; output one complete design image"
    }
  ],
  "settings": {
    "skill": "webpage",
    "resolution": "2k"
  },
  "options": {
    "external_task_id": ""
  }
}'
```

---

## Query Task (By task ID)

### API Overview

- Method: `GET`
- Path: `/tasks`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

> Note: The API currently supports querying async tasks only

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `task_ids` | string | No | - | - | The task ID defined by the system that needs to be queried |
| `external_task_ids` | string | No | - | - | The custom task ID that needs to be queried |

#### Query Params Field Notes

- `task_ids`: Query parameter; provide the value in the URL query string
- `task_ids`: When querying a task, you can choose between two query methods: task_ids and external_task_ids, but you cannot use them simultaneously
- `task_ids`: Support batch queries, separated by ","
- `external_task_ids`: Query parameter; provide the value in the URL query string
- `external_task_ids`: When querying a task, you can choose between two query methods: task_ids and external_task_ids, but you cannot use them simultaneously
- `external_task_ids`: Support batch queries, separated by ","

### Request Example

```bash
curl --location 'https://api-singapore.klingai.com/tasks?task_ids=123' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

```bash
curl --location 'https://api-singapore.klingai.com/tasks?external_task_ids=123' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

### Response Example

```json
{
  "code": 0, // Error code. See Error Codes for details
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "id": "893605946402811985", // The task ID being queried
      "status": "string", // Task status, Enum values: submitted, processing, succeeded, failed
      "message": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "create_time": 1781080778802, // Task creation time, Unix timestamp, unit ms
      "update_time": 1781080794151, // Task update time, Unix timestamp, unit ms
      "external_id": "string", // The custom task ID for this task (if any)
      "outputs": [
        {
          "type": "video", // When the generated result is "video", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Video ID, generated by the system
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // URL for generating result with watermark, hotlink protection format
          "duration": "string" // The duration of the generated video, in seconds
        },
        {
          "type": "image", // When the generated result is "image", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // Image download URL with watermark, protected URL
          "group_id": "string" // Only appears when generating grouped images, used to mark grouping relationships
        },
        {
          "type": "audio", // When the generated result is "audio", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Audio ID, generated by the system
          "mp3_url": "string", // Generated MP3 URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "wav_url": "string", // Generated WAV URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "mp3_duration": "string", // The duration of the generated MP3 format audio, in seconds
          "wav_duration": "string" // The duration of the generated WAV format audio, in seconds
        },
        {
          "type": "voice", // When the generated result is "voice", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Voice ID, generated by the system
          "name": "string", // Voice name
          "url": "string", // Material download link
          "owned_by": "string", // Voice source, kling is the official voice library, and the number is the creator ID
          "status": "succeeded" // Voice status. Enum values: succeeded, deleted
        },
        {
          "type": "element", // When the generated result is "element", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Element ID, generated by the system
          "name": "string", // Element name
          "description": "string", // Element description
          "element_type": "string", // Element type, divided into video character element and multi-image element, enumeration values are: video_character_elements and multi_image_elements
          "references": [ // Related materials of element
            {
              "type": "image", // When returning 'image' materials, the enumeration values for each content type are: image, video, voice
              "role": "string", // Image reference material attributes are divided into frontal reference images and other reference images, with enumeration values of frontal and reference, respectively
              "url": "string" // Material download link
            },
            {
              "type": "video", // When returning "video" materials, the enumeration values for each content type are: image, video, voice
              "role": "refer", // Video reference material attribute, fixed value: refer
              "url": "string" // Material download link
            },
            {
              "type": "voice", // When "voice" material is returned, enumeration values of each content type: image, video, voice
              "role": "refer", // Voice reference material attribute, fixed value: refer
              "url": "string", // Material download link
              "id": "string", // Voice ID
              "name": "string", // Voice name
              "owned_by": "string" // Voice source. kling means official voice library; numbers are creator IDs
            }
          ],
          "owned_by": "string", // Element source. kling means the official Element library; numbers are creator IDs
          "status": "string", // Element status. Enum values: succeeded, deleted
          "tags": [ // Element label related information
            {
              "id": 1, // Tag ID
              "name": "string", // Tag name
              "description": "string" // Tag description
            }
          ]
        }
      ],
      "billing": [ // When task consumes balances from multiple cash types, the system will return multiple records.
        {
          "charge_type": "string", // Consumption account type: If the consumption is of balance, the parameter value is "cash"; if it is of resource package, the parameter value is "unit"
          "cash_type": "string", // Balance type. Only applicable when charge_type=cash. If the consumption is the official quota, the parameter value is balance. If the consumption is the test quota, the parameter value is test_balance. If the consumption is the reward quota, the parameter value is reward_balance.
          "amount": "string", // Deduction amount; In the balance deduction situation (charge_type=cash), it represents the discount price deducted from the balance, and in the resource package deduction situation (charge_type=unit), it represents the deduction amount of units; decimal system
          "currency": "string", // Consumption unit, which only exists in the consumption balance scenario (charge_type=cash), with a fixed parameter value of CNY/USD
          "package_type": "string", // Consumable resource bundle type, which only exists in the consumable resource bundle scenario (charge_type=unit), with fixed enumeration values: video, image, audio
          "list_price": "string" // Balance deduction list price only exists in the consumption limit scenario (charge_type=cash)
        }
      ]
    }
  ]
}
```

---

## Query Task (By Cursor)

### API Overview

- Method: `POST`
- Path: `/tasks`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

> Note: The API currently supports querying async tasks only

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `start_time` | string | No | `end_time - 30 days` | - | Start time for task creation filtering |
| `end_time` | string | No | `current time` | - | End time for task creation filtering |
| `cursor` | string | No | - | - | Continuation cursor, i.e. query starting point |
| `limit` | int | No | `100` | - | Query the number of tasks |
| `filters` | array | No | - | - | Query task filtering criteria, such as task status and function type |
| `filters[].key` | string | No | - | `status`, `product_type` | Filtering dimensions, currently supporting filtering based on task status and other conditions |
| `filters[].values` | array | No | - | - | Filter value |

#### Request Body Field Notes

- `start_time`: Unix timestamp, in milliseconds
- `start_time`: The default value is end_time - 30 days
- `start_time`: Start time must be earlier than end time
- `end_time`: The default value is current time
- `end_time`: Unix timestamp, in milliseconds
- `end_time`: End time must be later than start time
- `cursor`: Use the next_cursor returned by the previous query
- `cursor`: When cursor is not empty, start_time and end_time are ignored
- `limit`: Maximum value: 500
- `filters`: Load with key/value format:
  ```json
  "filters": [
    {
      "key": "status", // Filter dimension by task status, fixed value: status
      "values": ["succeeded"]
    },
    {
      "key": "product_type", // Filter dimension by function type, fixed value: product_type
      "values": ["image"]
    }
  ]
  ```
- `filters[].key`: status: filter by task status
  - product_type: filter by function type
- `filters[].values`: status: submitted, processing, succeeded, failed
- `filters[].values`: product_type: video, image, try_on

### Request Example

```bash
curl --location 'https://api-singapore.klingai.com/tasks' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --data '{
    "start_time": "1781193600000",
    "end_time": "1781516352968",
    "cursor": "",
    "limit": 500,
    "filters": [
      {
        "key": "status",
        "values": ["succeeded"]
      },
      {
        "key": "product_type",
        "values": ["image"]
      }
    ]
  }'
```

### Response Example

```json
{
  "code": 0, // Error code. See Error Codes for details
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "result": [
      {
        "id": "string", // The task ID being queried
        "status": "string", // Task status, Enum values: submitted, processing, succeeded, failed
        "message": "string", // Task status information, displaying the failure reason when the task fails
        "create_time": 1781080778802, // Task creation time, Unix timestamp, unit ms
        "update_time": 1781080794151, // Task update time, Unix timestamp, unit ms
        "external_id": "string", // The custom task ID for this task (if any)
        "outputs": [
        {
          "type": "video", // When the generated result is "video", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Video ID, generated by the system
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // URL for generating result with watermark, hotlink protection format
          "duration": "string" // The duration of the generated video, in seconds
        },
        {
          "type": "image", // When the generated result is "image", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // Image download URL with watermark, protected URL
          "group_id": "string" // Only appears when generating grouped images, used to mark grouping relationships
        },
        {
          "type": "audio", // When the generated result is "audio", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Audio ID, generated by the system
          "mp3_url": "string", // Generated MP3 URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "wav_url": "string", // Generated WAV URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "mp3_duration": "string", // The duration of the generated MP3 format audio, in seconds
          "wav_duration": "string" // The duration of the generated WAV format audio, in seconds
        },
        {
          "type": "voice", // When the generated result is "voice", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Voice ID, generated by the system
          "name": "string", // Voice name
          "url": "string", // Material download link
          "owned_by": "string", // Voice source, kling is the official voice library, and the number is the creator ID
          "status": "succeeded" // Voice status. Enum values: succeeded, deleted
        },
        {
          "type": "element", // When the generated result is "element", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Element ID, generated by the system
          "name": "string", // Element name
          "description": "string", // Element description
          "element_type": "string", // Element type, divided into video character element and multi-image element, enumeration values are: video_character_elements and multi_image_elements
          "references": [ // Related materials of element
            {
              "type": "image", // When returning 'image' materials, the enumeration values for each content type are: image, video, voice
              "role": "string", // Image reference material attributes are divided into frontal reference images and other reference images, with enumeration values of frontal and reference, respectively
              "url": "string" // Material download link
            },
            {
              "type": "video", // When returning "video" materials, the enumeration values for each content type are: image, video, voice
              "role": "refer", // Video reference material attribute, fixed value: refer
              "url": "string" // Material download link
            },
            {
              "type": "voice", // When "voice" material is returned, enumeration values of each content type: image, video, voice
              "role": "refer", // Voice reference material attribute, fixed value: refer
              "url": "string", // Material download link
              "id": "string", // Voice ID
              "name": "string", // Voice name
              "owned_by": "string" // Voice source. kling means official voice library; numbers are creator IDs
            }
          ],
          "owned_by": "string", // Element source. kling means the official Element library; numbers are creator IDs
          "status": "string", // Element status. Enum values: succeeded, deleted
          "tags": [ // Element label related information
            {
              "id": 1, // Tag ID
              "name": "string", // Tag name
              "description": "string" // Tag description
            }
          ]
        }
      ],
        "billing": [ // When task consumes balances from multiple cash types, the system will return multiple records.
          {
            "charge_type": "string", // Consumption account type: cash for balance, unit for resource package
            "cash_type": "string", // Balance type. Only applicable when charge_type=cash. If the consumption is the official quota, the parameter value is balance. If the consumption is the test quota, the parameter value is test_balance. If the consumption is the reward quota, the parameter value is reward_balance.
            "amount": "string", // Deduction amount; In the balance deduction situation (charge_type=cash), it represents the discount price deducted from the balance, and in the resource package deduction situation (charge_type=unit), it represents the deduction amount of units; decimal system
            "currency": "string", // Consumption unit, which only exists in the consumption balance scenario (charge_type=cash), with a fixed parameter value of CNY/USD
            "package_type": "string", // Consumable resource bundle type, which only exists in the consumable resource bundle scenario (charge_type=unit), with fixed enumeration values: video, image, audio
            "list_price": "string" // Balance deduction list price only exists in the consumption limit scenario (charge_type=cash)
          }
        ]
      }
    ],
    "count": 1, // Number of query results
    "next_cursor": "string", // Cursor for querying subsequent results
    "has_more": true // Whether there are more results based on cursor information
  }
}
```
