> ## 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"
  }
}
```

`model: "kling-v4-long-image"`로 `POST /v1/images/generations`에 비동기 요청을 제출합니다. `data[0].task_id`를 얻은 후 `GET /v1/tasks/{task_id}`로 조회합니다. 요청당 긴 PNG 한 장을 반환하며 웹페이지 모드의 결과도 디자인 이미지입니다.

## 모드 선택

| 모드 | `skill` | 참조 이미지 | 길이 |
| - | - | - | - |
| 상품 상세 페이지 | `ecommerce` | `image_urls`: 상품 이미지 1–3장 필수 | `short` / `medium` / `long` |
| 웹페이지 디자인 | `webpage` | `image_with_roles`: 스타일 및 피사체 이미지 각각 최대 1장, 선택 사항 | `length` 생략 |

## 인증

**Authorization** `string` *required*

`Authorization: Bearer <token>`을 사용합니다. `<token>`은 APIMart API 키입니다.

## 요청 매개변수

**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 px와 2048 px이고 높이는 내용에 따라 달라집니다. `4K`는 지원하지 않습니다.

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

상품 페이지 전용이며 상품 이미지 1–3장이 필수입니다. 웹페이지에서는 생략하고 `image_with_roles`를 사용하세요. 공개 접근 가능한 이미지 직접 URL을 전달합니다. 로컬 파일은 [이미지 업로드 API](https://docs.apimart.ai/ko/api-reference/uploads/images.md)를 사용한 후 반환된 `url`을 전달하세요.

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

웹페이지 전용이며 선택 사항입니다. `style`과 `subject` 각각 최대 1장으로, 한쪽 또는 양쪽 모두 생략할 수 있습니다. 상품 페이지에서는 이 필드를 생략하세요.

**배열 항목**

**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을 실제 접근 가능한 직접 링크로 바꾸세요.

### 상품 긴 페이지: long + 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/ko/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
        }
      ]
    }
  }
}
```

`data.result.images[0].expires_at`에 표시된 초 단위 Unix 타임스탬프 이전에 다운로드하세요. 이후 링크는 만료됩니다.

> [!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` | 역할당 최대 1장입니다. 피사체 역할 중복도 허용되지 않습니다. |
| `` `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.