# Kling Image 4.0 Long — /images/generations

Kuaishou Kling Image 4.0의 긴 이미지 모드(Beta): 쇼핑몰 상세 페이지나 웹페이지 디자인 전체를 세로로 긴 이미지 한 장으로 만듭니다. 1K / 2K, C2PA 콘텐츠 자격 증명이 담긴 PNG 원본을 전달하며 페이지 종류, 길이, 해상도에 따라 과금합니다.

**엔드포인트:** `POST https://kovapi.com/v1/images/generations`

## 빠른 시작

다른 이미지 API와 같은 비동기 작업입니다. 제출하면 작업 id가 반환되고 폴링으로 결과를 받습니다. 상세 페이지에는 상품 사진 1~3장이 필요하고, 웹페이지는 텍스트만으로도 됩니다.

**1단계: 상세 페이지 작업 제출(skill, length, resolution과 상품 사진)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "첫 번째 이미지의 텀블러로 쇼핑몰 상세 페이지 만들기: 메인 비주얼, 셀링 포인트 세 가지, 사용 장면, 한국어 문구. 사진에 보이는 정보만 쓰고 사양을 지어내지 말 것", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'
```

응답(HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}
```

**2단계 · `status`가 `succeeded` 또는 `failed`가 될 때까지 2~3초마다 조회**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

성공했을 때의 응답

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}
```

**3단계: data[0].url을 내려받습니다. Kling이 전달한 PNG 긴 이미지 원본(너비 1024 / 2048px, 높이는 내용에 따라 다름)이며 7일간 보관됩니다.**

**전체 예제(Python: 제출 → 대기 → 로컬에 저장)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 웹페이지: 이미지는 없어도 됩니다
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "스페셜티 커피 로스터 노스바운드 커피의 홈페이지: 메인 이미지와 제목, 대표 원두 세 가지, 브랜드 이야기, 푸터, 한국어 문구, 따뜻하고 미니멀한 스타일",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 요청 파라미터

`POST /v1/images/generations`의 요청 본문(JSON):

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| model | string | 예 | 모델 ID: `kling-image-4.0-long`. |
| prompt | string | 예 | 그릴 내용. 이미지-투-이미지에서는 무엇을 어떻게 바꿀지 적으세요. |
| skill | string | 아니오 | 페이지 종류: `ecommerce`(쇼핑몰 상세 페이지, images에 상품 사진 1~3장) 또는 `webpage`(웹페이지 디자인). 생략하면 이미지가 있으면 ecommerce, 없으면 webpage입니다. |
| length | string | 아니오 | 상세 페이지 길이: `short`(약 2~5개 섹션), `medium`(기본값, 약 6~10개), `long`(약 11~18개). 웹페이지에는 쓰지 않습니다. |
| resolution | string | 아니오 | `1K`(기본값, 너비 1024px) 또는 `2K`(너비 2048px). 4K는 없습니다. |
| image / images | string / array | 아니오 | 상세 페이지: 상품 사진 1~3장(필수). 웹페이지: 최대 2장이며 기본적으로 첫 번째는 주체 참조, 두 번째는 스타일 참조입니다. jpg / png, 각 변 300px 이상, 가로세로 비율 2:5~5:2. 장당 $0.003이 추가됩니다. |
| image_roles | array | 아니오 | 웹페이지 전용: images의 각 이미지에 대응하며 `subject` 또는 `style`, 각각 최대 한 장. 예: `["style", "subject"]`. |
| n | integer | 아니오 | 요청당 긴 이미지 1장만: n은 1만 가능합니다. |
| callback_url | string | 아니오 | 작업이 끝나면 결과를 보낼 주소. 아래 웹훅 부분을 보세요. |

## 가격

페이지 종류, 길이, 해상도에 따른 장당 과금이며 참조 이미지는 장당 $0.003이 추가됩니다. 제출할 때 예치하고 실패하면 전액 돌려드립니다.

| 종류 | 1K · 장당 크레딧 | 1K · 장당 가격(USD) | 2K · 장당 크레딧 | 2K · 장당 가격(USD) |
| --- | --- | --- | --- | --- |
| 쇼핑몰 상세 페이지 · 짧게 | 47 | $0.235 | 56 | $0.28 |
| 쇼핑몰 상세 페이지 · 보통 | 94 | $0.47 | 109 | $0.545 |
| 쇼핑몰 상세 페이지 · 길게 | 156 | $0.78 | 172 | $0.86 |
| 웹페이지 | 109 | $0.545 | 119 | $0.595 |

## 크기와 형식

- 너비 고정: 1K는 1024px, 2K는 2048px. 높이는 내용에 따라 달라집니다(11-20 실측 4,257~16,270px).

- C2PA 콘텐츠 자격 증명이 담긴 PNG 원본이며 자르거나 크기를 바꾸지 않습니다. 2K 긴 이미지는 수십 MB가 될 수 있습니다.

- 요청당 완성된 긴 이미지 한 장을 반환하며, HTML이나 편집 가능한 디자인 파일은 반환하지 않습니다.

## 프롬프트 작성

- 페이지 목적, 언어, 섹션 순서, 셀링 포인트와 문구를 적으세요. 원하는 언어로 프롬프트를 쓰고 "한국어 문구"처럼 적어 주세요.

- 실제 상품 정보만 적고 "제공한 상품 정보만 쓰고 사양을 지어내지 말 것"을 더해 주세요. 모델은 준 내용을 쓰고 세부 내용을 덧붙일 수도 있습니다.

- 프롬프트에서 첫 번째, 두 번째 이미지는 @image1, @image2로 가리킬 수 있습니다.

## 작업 상태와 응답 필드

`GET /v1/images/jobs/{id}`는 아래 상태를 돌려줍니다. 각 필드의 설명은 [비동기 작업](https://docs.kovapi.com/ko/guide/async-jobs#fields)에 있습니다. 2~3초마다 조회하거나 웹훅을 쓰세요.

| 상태 | 의미 |
| --- | --- |
| queued | 대기 중. `queue_position`(앞에 있는 작업 수)과 `eta_seconds`(예상 대기 시간)가 함께 옵니다. |
| processing | 생성 중. |
| succeeded | 완료. 결과는 `data[0].url`, 과금 내역은 `usage`에 있습니다. |
| failed | 실패. 사유는 `error`에 있고, 예약된 크레딧은 전액 환불됩니다. |

한 계정은 최대 50개 작업을 동시에 생성하며, 그보다 많은 작업은 제출 순서대로 대기합니다. 15분이 지나도 시작되지 않은 작업은 자동으로 실패 처리되고 전액 환불됩니다. 작업 기록은 3일, 이미지 링크는 7일 동안 보관됩니다.

## 생성 시간

실측(11-20): 1K 약 1.5~2.5분, 2K 약 2.5분. 페이지가 길수록 오래 걸리고, 혼잡할 때는 더 걸릴 수 있습니다.

## 오류와 환불

제출 단계의 오류는 HTTP 4xx / 5xx로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 [오류 코드](https://docs.kovapi.com/ko/guide/errors)에 있습니다.

### 제출할 때 돌아오는 오류

| HTTP | code | 원인 | 조치 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` 요청에 `prompt`가 없습니다. | `prompt`를 추가하세요. |
| 400 | invalid_request | 참조 이미지를 읽을 수 없거나(링크가 열리지 않음, 이미지가 아님, 16MB 초과 등. `message`에 몇 번째인지와 이유가 적혀 있습니다), `/v1/images/edits`에 참조 이미지가 없거나, 요청 본문이 JSON 객체가 아니거나, `n`이 정수가 아닙니다. | `message`에 적힌 대로 고친 뒤 다시 제출하세요. |
| 400 | unsupported_resolution | 이 모델은 선택한 해상도 등급을 제공하지 않습니다(예: Grok 이미지 생성에는 4K가 없습니다). | 다른 등급을 고르세요. 모델별로 지원하는 등급은 각 모델 문서에 있습니다. |
| 400 | model_not_found | 모델 ID의 철자가 틀렸거나, `model`이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우). | `GET /v1/models` 또는 [API 레퍼런스](https://docs.kovapi.com/ko/api)에 있는 모델 ID를 쓰세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 [서비스 상태](https://kovapi.com/ko/status)에서 볼 수 있습니다. |
| 503 | service_unavailable | 참조 소재 저장 실패처럼 당사 측에서 일시적인 오류가 났습니다. `/v1/responses`는 잠시 요청을 처리할 수 없을 때도 `Retry-After`와 함께 503을 돌려줍니다. | 잠시 후 다시 시도하세요. |

### 작업 실패(`status`가 `failed`)

| code | 언제 나오나요 | 조치 |
| --- | --- | --- |
| moderation_blocked | 이미지: 모델 제공사의 안전 시스템이 프롬프트나 참조 이미지를 거부했습니다(코드가 `content_policy_violation`일 수도 있습니다). | 프롬프트를 고쳐 쓰거나 참조 이미지를 바꾸세요. 그대로 다시 제출하면 대개 다시 거부됩니다. |
| upstream_error | 그 밖의 실패: 자동 재시도 후에도 실패했거나, 15분 동안 기다려도 시작되지 않았거나, 업스트림이 이유 없이 거부한 경우 등입니다. 구체적인 내용은 `message`에 있습니다. | 다시 제출하면 대개 성공합니다. |

## 조회 대신 웹훅으로 받기

제출할 때 `callback_url`을 넣으면 작업이 끝나는 즉시(성공이든 실패든) 게이트웨이가 조회 엔드포인트와 똑같은 결과를 그 URL로 보냅니다. 서명이 포함되며, 전송에 실패하면 자동으로 재시도합니다. 콘솔의 「설정 → 웹훅」에서 계정 전체에 쓸 주소를 지정할 수도 있습니다. [웹훅 문서 →](https://docs.kovapi.com/ko/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "스페셜티 커피 로스터 노스바운드 커피의 홈페이지: 메인 이미지와 제목, 대표 원두 세 가지, 브랜드 이야기, 푸터, 한국어 문구, 따뜻하고 미니멀한 스타일", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'
```
