
이 Kling Image 4.0 API 가이드는 API 키 발급부터 완성된 이미지를 받기까지의 과정을 안내합니다. cURL 호출 한 번, 대기 시간이 제한된 Python 폴링 루프, 그리고 kling-4.0-image와 kling-4.0-long-image의 모든 입력 모드에 대해 바로 쓸 수 있는 JSON 본문을 제공합니다. 먼저 Kling Image 4.0 플레이그라운드에서 시험해 보세요. 아래의 모든 요청 본문은 PoYo 문서를 따릅니다.
cURL로 보내는 첫 Kling Image 4.0 API 요청
PoYo 대시보드에서 키를 만들고 서버에 POYO_API_KEY로 보관하세요. 그런 다음 2K 텍스트-이미지 태스크를 제출합니다.
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-4.0-image",
"input": {
"prompt": "High fashion model wearing a dress made of living moss, standing in an abandoned greenhouse, shafts of light, editorial photography",
"size": "16:9",
"resolution": "2K"
}
}'
응답에는 code: 200과 data.task_id가 있고 status: "not_started" 상태입니다. 제출된 태스크는 아직 완성된 이미지가 아닙니다. 다음 명령으로 확인하세요.
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
상태는 not_started, running, finished, failed입니다. finished이면 data.files에 이미지마다 file_url과 file_type: "image"를 담은 항목이 있고, data.credits_amount에 태스크 비용이 표시됩니다. failed이면 data.error_message를 확인하세요.
대기 시간이 제한된 Python 폴링 루프
이 코드는 백엔드에서 requests로 실행됩니다. HTTP 상태와 본문의 code 필드를 모두 확인하고(검증 오류는 HTTP 200과 code: 400으로 올 수 있음), failed에서 중단하며, 20분이 지나면 재제출하지 않고 대기를 멈춥니다. 두 번 제출하면 두 번 과금되기 때문입니다.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(resp):
resp.raise_for_status()
body = resp.json()
if body.get("code") != 200:
raise RuntimeError(f"PoYo error {body.get('code')}: {body.get('error')}")
return body["data"]
def run(payload, max_wait=1200, every=10):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
return [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
time.sleep(every)
raise TimeoutError("still running, poll task " + task_id + " again later")
urls = run({
"model": "kling-4.0-image",
"input": {
"prompt": "A ceramic pour-over kettle on a walnut counter, morning window light",
"size": "1:1",
"resolution": "2K",
},
})
print(urls)
오래 걸리는 작업에는 대신 페이로드 최상위에 "callback_url": "https://your-domain.com/poyo-hook"을 추가하세요. 태스크가 완료되거나 실패하면 PoYo가 같은 태스크 데이터(code/data 래퍼 제외)를 POST로 보내며, X-Webhook-Signature에 HMAC-SHA256 서명이 포함됩니다. 검증 방법은 웹훅 문서에 있습니다.
image_urls로 이미지-이미지 생성
image_urls에 공개 HTTP(S) URL을 1–10개 전달합니다. 배열 순서대로 첫 번째가 @Image1, 두 번째가 @Image2입니다. 프롬프트에서 각 이미지의 역할을 정하고, 무엇이 바뀌지 않아야 하는지 명시하세요.
{
"model": "kling-4.0-image",
"input": {
"prompt": "Turn @Image1 into a late-evening scene with warm window light. Keep the furniture, layout and camera angle of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"resolution": "2K"
}
}
image_urls는 이미지가 한 장이어도 배열이어야 합니다. 각 이미지는 최대 30 MB, 너비와 높이 최소 300 px, 너비/높이 비율 0.4–2.5여야 합니다.
kling_elements로 일관된 피사체 유지
엘리먼트는 하나의 캐릭터나 오브젝트를 2–4개 각도에서 보여 주는 묶음이며, 정면 시점이 첫 번째입니다. 엘리먼트를 쓰려면 image_urls 항목이 최소 1개 필요하고, 최대 7개까지 전달할 수 있습니다. 이미지와 엘리먼트 합계는 최대 10개입니다.
{
"model": "kling-4.0-image",
"input": {
"prompt": "Place @Element1 sitting on the sofa in @Image1, reading a book in warm evening light. Keep the room layout of @Image1 unchanged.",
"image_urls": ["https://example.com/living-room.png"],
"kling_elements": [
{
"element_input_urls": [
"https://example.com/character-front.png",
"https://example.com/character-side.png",
"https://example.com/character-back.png"
]
}
],
"resolution": "2K"
}
}
이 요청의 비용은 2K 이미지 13 크레딧, 참조 이미지 1, 엘리먼트 1을 더한 15 크레딧($0.075)입니다.
enable_sequential로 이미지 세트 만들기
enable_sequential: true이면 n은 2–10(기본값 4)이며, 모델이 같은 피사체와 스타일을 가진 하나의 세트로 이미지를 기획해 순서대로 반환합니다. 꺼져 있으면 n 1–9로 독립 이미지를 반환합니다.
{
"model": "kling-4.0-image",
"input": {
"prompt": "A four-panel story of a paper boat drifting from a rainy city gutter to a calm sunny lake, same boat in every panel, watercolor style",
"size": "3:2",
"enable_sequential": true,
"n": 4
}
}
출시 당일 테스트(PoYo 프로덕션 API, 2026년 11월 19일)에서 16:9, 2K, n: 4 세트는 새벽, 정오, 일몰, 밤에 걸쳐 같은 라이더, 바이크, 의상을 유지한 2720×1536 이미지 4장을 반환했습니다. 비용은 52 크레딧이고 제출부터 결과까지 약 4.9분이 걸렸습니다.
롱 웹페이지와 이커머스 페이지
모델 ID를 kling-4.0-long-image로 바꾸고 skill을 선택합니다. 다음은 스타일 참조를 선택적으로 따르는 웹페이지 디자인입니다.
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a long image for a specialty coffee brand's official website, including the hero section, product showcase, roasting philosophy, store information, and footer. Follow the visual style of @StyleImage. All text on the page is in English.",
"skill": "webpage",
"style_image_url": "https://example.com/style-reference.png",
"resolution": "2K"
}
}
상품 사진 한 장으로 만드는 이커머스 상세 페이지입니다.
{
"model": "kling-4.0-long-image",
"input": {
"prompt": "Design a product detail page for the insulated water bottle in @Image1: hero shot, key features, capacity and size, materials, and lifestyle scenes. All text on the page is in English.",
"skill": "ecommerce",
"image_urls": ["https://example.com/water-bottle.png"],
"length": "medium",
"resolution": "1K"
}
}
팁: 페이지 언어를 지정하세요. 테스트에서 문구 언어를 지정하지 않은 영어 웹페이지 프롬프트는 페이지에 중국어 텍스트가 들어간 결과를 반환했습니다. 프롬프트에 "All text on the page is in English."를 추가하자 해결되었기 때문에 위의 두 본문 모두 이 문장으로 끝납니다. 1K 웹페이지 테스트는 약 1.7–2.2분 만에 1024×4257 이미지 1장을 반환했고 비용은 110 크레딧입니다.
image_urls와 length는 ecommerce용이고, style_image_url과 subject_image_url은 webpage용입니다. 페이지 길이와 8K 출력에 대한 자세한 내용은 Kling Image 4.0 API로 만드는 8K 및 롱 이미지를 참고하세요.
결과 저장하기
각 files[].file_url은 PNG를 가리킵니다. 앱에서 핫링크하지 말고 자체 스토리지로 복사하세요. 출시 당일 테스트에서 확인한, 미리 대비해야 할 세 가지는 다음과 같습니다.
- 크기. 16:9 8K 이미지 1장은 약 128 MB의 10880×6144 PNG였습니다. 메모리에 올리지 말고 디스크로 스트리밍하고, 클라이언트의 읽기 타임아웃을 늘리세요.
- 알파 채널. 불투명한 이미지여도 다운로드 파일은 RGBA PNG였습니다. 파이프라인, CDN, 인쇄 워크플로가 RGB나 JPEG를 기대한다면 다운로드 후 변환하세요.
- 순서. 이미지 세트는 순서대로 반환되므로
files의 인덱스가 스토리보드나 슬라이드 세트의 프레임 번호입니다.
제출 전에 확인할 검증 규칙
| 규칙 | 모델 |
|---|---|
prompt 1–50,000자, 공백만으로 구성 불가 | 둘 다 |
image_urls 1–10개, 각각 30 MB, ≥300 px, 비율 0.4–2.5 | kling-4.0-image |
kling_elements ≤ 7, 각각 URL 2–4개, image_urls가 있을 때만, 이미지 + 엘리먼트 ≤ 10 | kling-4.0-image |
n은 세트가 아니면 1–9, enable_sequential: true이면 2–10 | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce"는 image_urls 1–3개 필요, resolution 1K / 2K | kling-4.0-long-image |
추가 필드 불가(output_format, seed, negative_prompt는 거부됨) | 둘 다 |
처리해야 할 오류
code | 의미 | 대응 |
|---|---|---|
| 400 | 잘못된 파라미터 | 본문을 수정하고, 그대로 재시도하지 않음 |
| 401 | API 키 누락 또는 무효 | 헤더 확인 |
| 402 | 크레딧 부족 | 충전 후 재제출 |
| 429 | 속도 제한 | 백오프 후 나중에 재시도 |
| 500 / 502 / 503 | 서버 또는 업스트림 오류 | 백오프와 함께 제출 재시도 |
failed 태스크는 과금되지 않으므로 실패 후 재제출은 안전합니다. 하지만 클라이언트 쪽 타임아웃 후 재제출하는 것은 안전하지 않습니다. 먼저 같은 task_id를 폴링하세요.
첫 청구 금액 계산 방법
kling-4.0-image의 비용은 이미지당 가격에 이미지 수를 곱하고, image_urls 항목과 엘리먼트마다 요청당 1회 1 크레딧을 더한 값입니다. 1 크레딧 = $0.005 기준입니다.
| 요청 | 크레딧 | USD |
|---|---|---|
| 위의 첫 cURL 호출(2K, 이미지 1장) | 13 | $0.065 |
| 같은 프롬프트, 8K | 32 | $0.16 |
| 위의 엘리먼트 편집(2K, 이미지 1장 + 엘리먼트 1개) | 15 | $0.075 |
| 2K 이미지 4장 세트 | 52 | $0.26 |
| 1K 웹페이지, 참조 없음 | 110 | $0.55 |
| 1K medium 이커머스 페이지, 상품 사진 1장 | 95 | $0.475 |
전체 가격표와 더 많은 예시는 Kling Image 4.0 API 가격에 있습니다. 두 모델 ID의 개요는 Kling Image 4.0이란을 참고하세요.
자주 묻는 질문
Python으로 Kling Image 4.0 API를 호출하려면 어떻게 하나요?
requests로 JSON 본문을 https://api.poyo.ai/api/generate/submit에 POST하고, data.task_id를 읽은 뒤 finished가 될 때까지 /api/generate/status/{task_id}를 폴링해 files[].file_url을 읽습니다. 위의 루프가 대기 기한과 오류 검사를 포함해 이 과정을 수행합니다.
Kling Image 4.0 API 모델 ID는 무엇인가요?
텍스트-이미지, 편집, 이미지 세트에는 kling-4.0-image, 롱 웹페이지와 이커머스 페이지에는 kling-4.0-long-image를 사용합니다. kling-4-0-image는 페이지 슬러그일 뿐입니다.
Kling Image 4.0 API는 웹훅을 지원하나요?
네. 요청 최상위에 callback_url을 추가하세요. 태스크가 완료되거나 실패하면 PoYo가 서명된 POST를 보냅니다.
Kling Image 4.0 API에서 JPEG로 출력할 수 있나요? 출력 형식 필드가 없으며 결과는 PNG입니다. 저희가 다운로드한 파일은 불투명한 이미지여도 RGBA PNG였으므로, JPEG가 필요하면 직접 변환하세요.
Kling Image 4.0 롱 웹페이지가 왜 다른 언어로 나왔나요? 프롬프트에서 페이지 문구의 언어를 지정하지 않으면 모델이 언어를 임의로 선택할 수 있습니다. 예를 들어 "All text on the page is in English."처럼 명시하세요.