how-tos

Kling Image 4.0 API 가이드: cURL과 Python으로 첫 요청 보내기

Poyo.ai Team
7 min read
Share:

Kling Image 4.0 API 가이드: cURL과 Python으로 첫 요청 보내기

이 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.5kling-4.0-image
kling_elements ≤ 7, 각각 URL 2–4개, image_urls가 있을 때만, 이미지 + 엘리먼트 ≤ 10kling-4.0-image
n은 세트가 아니면 1–9, enable_sequential: true이면 2–10kling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce"는 image_urls 1–3개 필요, resolution 1K / 2Kkling-4.0-long-image
추가 필드 불가(output_format, seed, negative_prompt는 거부됨)둘 다

처리해야 할 오류

code의미대응
400잘못된 파라미터본문을 수정하고, 그대로 재시도하지 않음
401API 키 누락 또는 무효헤더 확인
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
같은 프롬프트, 8K32$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."처럼 명시하세요.

Share: