KovAPIKovAPI
kling-image-4.0-long

Kling Image 4.0 Long · API

POST https://kovapi.com/v1/images/generations

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

플레이그라운드에서 사용해 보기 →

빠른 시작

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

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

curl
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)

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

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

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

성공했을 때의 응답

JSON
{
  "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: 제출 → 대기 → 로컬에 저장)

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"])

인증

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

요청 파라미터

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

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

가격

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

종류1K · 장당 크레딧1K · 장당 가격(USD)2K · 장당 크레딧2K · 장당 가격(USD)
쇼핑몰 상세 페이지 · 짧게47$0.23556$0.28
쇼핑몰 상세 페이지 · 보통94$0.47109$0.545
쇼핑몰 상세 페이지 · 길게156$0.78172$0.86
웹페이지109$0.545119$0.595

크기와 형식

  • 너비 고정: 1K는 1024px, 2K는 2048px. 높이는 내용에 따라 달라집니다(11-20 실측 4,257~16,270px).
  • C2PA 콘텐츠 자격 증명이 담긴 PNG 원본이며 자르거나 크기를 바꾸지 않습니다. 2K 긴 이미지는 수십 MB가 될 수 있습니다.
  • 요청당 완성된 긴 이미지 한 장을 반환하며, HTML이나 편집 가능한 디자인 파일은 반환하지 않습니다.

프롬프트 작성

  • 페이지 목적, 언어, 섹션 순서, 셀링 포인트와 문구를 적으세요. 원하는 언어로 프롬프트를 쓰고 "한국어 문구"처럼 적어 주세요.
  • 실제 상품 정보만 적고 "제공한 상품 정보만 쓰고 사양을 지어내지 말 것"을 더해 주세요. 모델은 준 내용을 쓰고 세부 내용을 덧붙일 수도 있습니다.
  • 프롬프트에서 첫 번째, 두 번째 이미지는 @image1, @image2로 가리킬 수 있습니다.

작업 상태와 응답 필드

GET /v1/images/jobs/{id}는 아래 상태를 돌려줍니다. 각 필드의 설명은 비동기 작업에 있습니다. 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로 바로 돌아오며, 작업은 만들어지지 않고 과금되지 않습니다. 작업이 접수된 뒤의 실패는 작업 조회 결과로 알려 주며, 예약된 크레딧은 전액 환불됩니다. 전체 코드는 오류 코드에 있습니다.

제출할 때 돌아오는 오류

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

작업 실패(status가 failed)

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

조회 대신 웹훅으로 받기

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

curl · callback_url
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"}'