이커머스·웹페이지용 Kling Image 4.0 Long Image API 가이드
Kling Image 4.0 Long Image API로 1K·2K 세로형 이커머스 상세페이지와 웹페이지 디자인을 생성하세요. 듀얼 스킬 스키마, 티어, 타임아웃을 정리합니다.
Markdown으로 읽기일반 이미지 API는 스크롤형 이커머스 상품 상세페이지 전체나 여러 섹션으로 이루어진 랜딩페이지 목업을 요청하는 순간 한계에 부딪힙니다. 화면 비율은 9:16이나 21:9 정도에서 막히고, 조각내어 생성한 이미지 사이에서는 타이포그래피가 어긋나며, 개별 배너를 이어 붙이면 눈에 띄는 이음새가 남습니다. Kling Image 4.0 Long Image(kling-image-4-0-long-image)는 단 한 번의 POST /v1/images/generations 호출로 전체 세로 레이아웃을 하나의 일관된 세로형 PNG로 렌더링해 바로 이 워크플로를 해결합니다.
개별 2K·4K 스틸과 멀티 프레임 시리즈를 출력하는 Kling Image 4.0과 달리, Long Image 엔드포인트는 ecommerce와 webpage라는 두 가지 전용 레이아웃 스킬을 중심으로 설계되었으며 각 스킬은 고유한 참조 이미지 유형, 길이 제어, 티어별 가격 구조를 가집니다. 2026년 11월 하순 현재까지도 대부분의 검색 결과는 이 모델을 Kling 비디오나 일반 이미지 업스케일러와 혼동합니다. 이 가이드는 검증된 API 규격, 모든 가격 티어, 실제 유효성 검사 규칙, 그리고 수 분 걸리는 렌더링과 50 MB가 넘는 PNG 다운로드를 깔끔하게 처리하기 위한 프로덕션 엔지니어링 세부 사항을 정리합니다.
두 가지 스킬, 두 가지 엄격한 입력 규격
kling-image-4-0-long-image로 보내는 모든 요청은 settings.skill을 ecommerce 또는 webpage 중 하나로 명시해야 합니다. 두 모드의 참조 유형을 섞어 보내면 과금 전에 HTTP 400 유효성 검사 오류가 반환됩니다.
| 필드 / 규칙 | skill: "ecommerce" | skill: "webpage" |
|---|---|---|
| 주요 산출물 | 세로형 상품 상세페이지 (PDP) | 전체 스크롤 웹페이지 비주얼 디자인 |
| 참조 항목 유형 | refer_image (필수: 1~3장 사진) | style_refer_image (0subject_refer_image (0 |
| 참조 없는 텍스트 전용 호출 | 거부됨 (HTTP 400) | 허용됨 |
settings.length | short (~2–5개 섹션), medium (기본값, ~6–10), long (~11–18) | 무시됨 (생략) |
settings.resolution | 1k (너비 1024 px, 기본값) 또는 2k (너비 2048 px) | 1k (너비 1024 px, 기본값) 또는 2k (너비 2048 px) |
4k 해상도 | 미지원 (HTTP 400) | 미지원 (HTTP 400) |
| 출력 개수 | 항상 세로형 PNG 1장 (output.data[0].url) | 항상 세로형 PNG 1장 (output.data[0].url) |
모든 참조 이미지 URL은 공개 접근 가능한 HTTP(S) JPEG 또는 PNG 파일이어야 하며, 최대 30 MB, 각 변 최소 300픽셀, 가로세로 비율 2:5~5:2 조건을 충족해야 합니다. 참고로 kling-image-4-0-long-image에서는 element 참조를 지원하지 않습니다.
프롬프트 용량은 일반 이미지 생성기에 비해 매우 넉넉합니다. 영문 최대 166,000자 또는 비영문 최대 71,000자까지 허용됩니다(혼합 프롬프트는 english / 166000 + non_english / 71000 <= 1 충족 필요). 이 여유 공간 덕분에 모델이 제품 정보를 임의로 지어내지 않도록 섹션별 전체 문구, 검증된 사양 표, 성분 목록, 콜아웃 라벨을 그대로 제공할 수 있습니다.
실시간 가격 티어와 참조 이미지 계산
완료된 Long Image 작업마다 skill, resolution, 그리고 (ecommerce의 경우) length로 결정되는 고정 티어 요금 1건과, 첫 장부터 계산되는 입력 사진 1장당 참조 이미지 요금이 합산되어 청구됩니다. 실패하거나 잘못된 요청에는 요금이 부과되지 않습니다.
Kling Image 4.0 Long Image 비용
| 카테고리 | 가격 (USD) |
|---|---|
| Ecommerce · 1K · short | $0.2269 |
| Ecommerce · 2K · short | $0.2723 |
| Ecommerce · 1K · medium | $0.4538 |
| Ecommerce · 2K · medium | $0.5294 |
| Ecommerce · 1K · long | $0.7563 |
| Ecommerce · 2K · long | $0.8319 |
| Webpage · 1K | $0.5294 |
| Webpage · 2K | $0.5748 |
| 참조 이미지 | $0.003025 |
2026년 11월 20일 확인된 https://api.toklab.ai/v1/pricing 기준으로 8개 출력 티어는 다음과 같으며, 입력 참조 이미지 1장마다 $0.003025가 추가됩니다.
| 스킬 | 길이 | 해상도 | 출력 요율 | 참조 2장 포함 예시 |
|---|---|---|---|---|
ecommerce | short (~2–5개 섹션) | 1k | $0.2269 | $0.23295 |
ecommerce | short (~2–5개 섹션) | 2k | $0.2723 | $0.27835 |
ecommerce | medium (~6–10개 섹션) | 1k | $0.4538 | $0.45985 |
ecommerce | medium (~6–10개 섹션) | 2k | $0.5294 | $0.53545 |
ecommerce | long (~11–18개 섹션) | 1k | $0.7563 | $0.76235 |
ecommerce | long (~11–18개 섹션) | 2k | $0.8319 | $0.83795 |
webpage | 해당 없음 | 1k | $0.5294 | $0.53545 |
webpage | 해당 없음 | 2k | $0.5748 | $0.58085 |
1K에서 2K로의 가격 차이를 자세히 보세요. 1k에서 2k로 올릴 때 추가 비용은 webpage에서 $0.0454(+8.6%), ecommerce medium 및 long에서 $0.0756(+10%~+16.7%)에 불과합니다. 세로형 페이지에는 작은 UI 라벨, 사양 그리드, 본문 문구가 빽빽하게 들어가므로 최종 에셋은 소액의 추가 비용을 내더라도 2k(너비 2048 px)로 렌더링할 가치가 충분하며, 1k는 섹션 개요를 확정하기 전 저렴한 구조 초안 용도로 쓰기 좋습니다.

ecommerce vs webpage 실행을 위한 프롬프트 구조화
모델이 한 번의 패스로 스크롤 페이지 전체를 구성하므로 모호한 프롬프트는 반복적인 채우기 섹션이나 지어낸 사양을 낳습니다. 프롬프트를 와이어프레임 명세서처럼 작성하면 레이아웃 품질이 눈에 띄게 올라갑니다.
- 위에서 아래 순서대로 섹션을 나열하세요. 각 밴드에 번호를 명시합니다. 예를 들어
Section 1: 히어로 배너,Section 2: 3열 기능 콜아웃,Section 3: 매크로 질감 디테일,Section 4: 사양 표,Section 5: 관리 안내 및 푸터처럼 구성합니다. - 각 참조 사진을
@id로 고정하세요.ecommerce모드에서는 명확한 ID(front,spout,box)를 지정하고 어느 밴드에 어떤 각도를 쓸지 알려줍니다.webpage모드에서는 룩앤필(style_refer_image의@layout)과 히어로 제품(subject_refer_image의@product)을 분리합니다. - 정확한 문구와 수치를 직접 제공하세요. "그럴듯한 기술 사양을 추가해 줘"라고 쓰지 마세요. 나중에 잘못 생성된 수치를 리터칭하지 않으려면 원하는 소비전력, 치수, 소재, 헤드라인을 정확히 적어 넣어야 합니다.
settings.length를 섹션 수에 맞추세요.length: "short"안에 14개의 상세 밴드를 요청하면 작은 라벨이 뭉개질 정도로 타이포그래피가 압축됩니다. 2–5개 밴드는short, 6–10개는medium, 11–18개는long과 짝지으세요.
알맞은 이커머스 길이 티어 고르기
short, medium, long 중 무엇을 고를지는 시각적 호흡이자 예산 레버입니다. short 페이지(~2–5개 섹션, 1k $0.2269 / 2k $0.2723)는 히어로 컷, 핵심 셀링 포인트 3개, 간결한 사양 블록 하나만 필요한 단일 SKU 프로모션 카드, 모바일 우선 마켓플레이스 티저, 비교 스트립에 잘 맞습니다. medium 페이지(~6–10개 섹션, 1k $0.4538 / 2k $0.5294)는 대부분의 Shopify, Amazon A+, 크로스보더 스토어 상세페이지에 가장 실용적인 균형점입니다. 히어로 비주얼, 클로즈업 소재 컷, 사용 장면, 치수 표, 구성품까지 서사를 억지로 늘리지 않고 담을 수 있습니다.
long(~11–18개 섹션, 1k $0.7563 / 2k $0.8319)은 스토리텔링 밴드, 분해도 콜아웃, 단계별 사용 가이드, 인증 배지, FAQ 블록이 실제로 필요한 플래그십 전자제품, 가전, 멀티 옵션 키트에 아껴 두세요. 11개 이상 섹션을 채울 만큼 고유한 제품 정보가 충분하지 않으면 long 모드는 앞선 각도를 반복하거나 뻔한 라이프스타일 배너를 끼워 넣어 렌더링 시간과 예산을 모두 낭비하기 쉽습니다.
webpage 모드가 스타일 참조와 피사체 참조를 분리하는 이유
webpage 모드에서 style_refer_image와 subject_refer_image를 분리하면 단일 버킷 참조 API의 전형적인 실패 패턴—모델이 다른 브랜드의 제품을 내 레이아웃에 복사하거나, 내 제품 사진의 복잡한 배경을 사이트 UI 크롬으로 끌어오는 문제—을 방지할 수 있습니다. 에디토리얼 스크린샷이나 Figma 프레임을 style_refer_image로 전달하면 그리드 리듬, 컬러 토큰, 타이포그래피 위계, 버튼 스타일에만 적용되고, 깔끔한 스튜디오 제품 사진을 subject_refer_image로 전달하면 히어로와 기능 카드 전반에서 실제 제품 형태가 충실히 유지됩니다. 텍스트만으로 완전히 새로운 아트 디렉션을 원한다면 두 이미지 필드를 모두 생략하고 팔레트, 폰트 조합, 그리드 구조를 프롬프트에 직접 설명하세요.
생성된 페이지 게시 전 품질 검수
2k 해상도라도 생성된 롱 이미지는 스토어프런트나 클라이언트 덱에 올리기 전에 빠른 자동·시각 QA 관문을 거쳐야 합니다. 첫째, 렌더링된 모든 숫자, 단위, 성분 표기를 원본 프롬프트와 대조하세요. 빽빽한 사양 표의 작은 오타는 축소 미리보기보다 100% 확대 상태에서 훨씬 잘 보입니다. 둘째, 히어로 밴드부터 클로즈업 섹션까지 제품의 물리적 형태(버튼 위치, 로고, 포트, 비율)가 일관되게 유지되었는지 확인하세요. 셋째, 슬라이싱 후 390 px 모바일 뷰포트에서의 세로 가독성을 점검하세요. 2,048 px 너비에서 선명해 보이는 4열 데스크톱 기능 행도 스마트폰 화면에서는 읽기 어려울 수 있으므로, 굵고 대비가 높은 2열 또는 세로 스택형 모바일 카드로 프롬프트를 설계하는 편이 안전합니다.
두 가지 스킬의 전체 요청 예시
1. 이커머스 상품 상세페이지 (medium, 2k)
{
"model": "kling-image-4-0-long-image",
"contents": [
{"type": "refer_image", "url": "https://example.com/kettle-front.png", "id": "front"},
{"type": "refer_image", "url": "https://example.com/kettle-spout.jpg", "id": "spout"},
{
"type": "prompt",
"text": "Design a clean ecommerce product detail page for the matte black gooseneck kettle in @front. Section 1: Hero banner with headline 'Precision Pour 0.9L' and @front centered on warm stone. Section 2: Three feature cards covering 1200W rapid boil, 1-degree PID control, and 60-minute hold. Section 3: Macro close-up based on @spout highlighting laminar flow control. Section 4: Lifestyle pour-over brewing scene. Section 5: Dimension and electrical spec table (900 ml, 1200W, 120V, 304 stainless steel). Section 6: Box contents and care notes."
}
],
"settings": {
"skill": "ecommerce",
"length": "medium",
"resolution": "2k"
}
}2. 스타일 + 피사체 참조를 활용한 웹페이지 비주얼 디자인 (2k)
import os
import time
import requests
API_KEY = os.environ["TOKLAB_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "kling-image-4-0-long-image",
"contents": [
{"type": "style_refer_image", "url": "https://example.com/editorial-grid.png", "id": "grid"},
{"type": "subject_refer_image", "url": "https://example.com/chronograph.jpg", "id": "watch"},
{
"type": "prompt",
"text": (
"Create a vertical product launch webpage adopting the Swiss editorial grid, "
"high-contrast serif headings, and generous whitespace of @grid while featuring @watch. "
"Include: top navigation bar, full-bleed hero with @watch, three-card movement breakdown, "
"water-resistance specification band, and minimalist footer."
),
},
],
"settings": {"skill": "webpage", "resolution": "2k"},
}
resp = requests.post(
"https://api.toklab.ai/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["id"]
# Poll every 5s; long 2K layouts can take several minutes.
deadline = time.time() + 600
while time.time() < deadline:
status_resp = requests.get(
f"https://api.toklab.ai/v1/tasks/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
status_resp.raise_for_status()
data = status_resp.json()
if data.get("status") == "completed":
png_url = data["output"]["data"][0]["url"]
print("Ready:", png_url)
break
if data.get("status") == "failed":
raise RuntimeError(f"Long image task failed: {data}")
time.sleep(5)프로덕션 엔지니어링 노트: 타임아웃, 50 MB 이상 PNG 및 슬라이싱
kling-image-4-0-long-image를 백엔드 서비스에 연동하는 일은 빠른 1024×1024 이미지 생성기 연동과 운영 측면에서 세 가지가 다릅니다.
- 수 분 단위의 작업 지연 시간을 전제로 설계하세요.
long+2k이커머스 렌더링은 보통 몇 분이 걸립니다. 30초 타임아웃이 걸린 브라우저나 서버리스 함수에서 HTTP 연결을 열어 둔 채 기다리지 말고, 백그라운드 워커에 작업 ID를 큐잉해 최대 10분 한도로GET /v1/tasks/:id를 폴링하세요. - 대용량 PNG 다운로드는 스트리밍으로 처리하세요.
2k롱 이미지는 너비가 2,048픽셀이고 세로로 10,000~20,000픽셀 이상 뻗을 수 있어 완성된 PNG 파일이 50 MB를 넘을 수 있습니다. 넉넉한 읽기 타임아웃과 함께 스트리밍 다운로드(requests.get(url, stream=True))를 사용하고, 작은 컨테이너 메모리에 여러 개의 원본 비트맵을 한꺼번에 버퍼링하지 마세요. - 실제 스토어프런트 배포 전에 슬라이싱하고 재인코딩하세요. 마켓플레이스 플랫폼(Shopify, Amazon A+, Taobao/Tmall)과 모바일 브라우저는 단일 50 MB PNG에 불이익을 줍니다. 생성된 레이아웃 검수가 끝나면 마스터 PNG를 섹션 경계에 맞춰 자르고 각 슬라이스를 80–85% 품질의 WebP 또는 프로그레시브 JPEG로 변환해 빠르게 서빙하세요.
미리 막아야 할 흔한 HTTP 400 오류
엔드포인트를 호출하기 전에 다음 다섯 가지 조건을 검증하세요.
settings.skill누락 (반드시"ecommerce"또는"webpage"여야 함).skill: "ecommerce"에서refer_image가 0개이거나 3개를 초과함.webpage모드에refer_image를 보내거나,ecommerce모드에style_refer_image/subject_refer_image를 보냄.resolution: "4k"요청 (Long Image에는"1k"와"2k"만 존재).contents내 두 참조 항목에서 동일한id문자열을 중복 사용함.
표준 가로형·정사각형 캠페인 컷, 제품 라이프스타일 세트, 또는 한 프레임에 최대 10장의 참조 이미지가 필요한 작업이라면 Kling Image 4.0으로 라우팅하고, Kling Image 4.0 Long Image는 세로형 멀티 밴드 페이지 구성에 집중해 사용하세요.
출처
- TokLab Kling Image 4.0 Long Image 모델 페이지 — 인터랙티브 Playground, 실시간 1K/2K 티어 표 및 계산기.
- TokLab Kling Image 4.0 Long Image API 레퍼런스 — 공식 스키마, 글자 수 제한 및 유효성 검사 제약.
- TokLab 실시간 가격 API — 2026년 11월 20일 기준 기계 판독 가능 요율 피드.


