
Hướng dẫn Kling Image 4.0 API này đưa bạn từ API key đến ảnh hoàn chỉnh: một lệnh gọi cURL, một vòng lặp polling Python có giới hạn thời gian, rồi body JSON chạy được cho mọi chế độ input của kling-4.0-image và kling-4.0-long-image. Bạn có thể thử từng request trước trong playground Kling Image 4.0; mọi body request dưới đây đều theo tài liệu PoYo.
Request Kling Image 4.0 API đầu tiên với cURL
Tạo key trong dashboard PoYo và lưu trên server của bạn dưới tên POYO_API_KEY. Sau đó submit một task text-to-image 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"
}
}'
Phản hồi có code: 200 và data.task_id, với status: "not_started". Task đã submit chưa phải là ảnh hoàn chỉnh. Kiểm tra bằng:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Các trạng thái gồm not_started, running, finished và failed. Khi finished, data.files chứa một mục cho mỗi ảnh với file_url và file_type: "image", còn data.credits_amount cho biết chi phí của task. Khi failed, hãy đọc data.error_message.
Vòng lặp polling Python có giới hạn
Đoạn code này chạy trên backend của bạn với requests. Nó kiểm tra cả mã HTTP lẫn trường code trong body (lỗi xác thực có thể đến dưới dạng HTTP 200 với code: 400), dừng khi failed, và ngừng chờ sau 20 phút mà không submit lại, vì submit lần hai là bị tính phí lần hai.
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)
Với các job dài, hãy thêm "callback_url": "https://your-domain.com/poyo-hook" ở cấp ngoài cùng của payload. PoYo sẽ POST cùng dữ liệu task (không có lớp bọc code/data) khi task hoàn tất hoặc thất bại, được ký bằng HMAC-SHA256 trong X-Webhook-Signature; tài liệu webhook hướng dẫn cách xác minh.
Image-to-image với image_urls
Truyền 1 đến 10 URL HTTP(S) công khai trong image_urls. Ảnh đầu tiên là @Image1, ảnh thứ hai là @Image2, theo thứ tự trong mảng. Gán cho mỗi ảnh một vai trò trong prompt và nêu rõ những gì phải giữ nguyên.
{
"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 phải là một mảng ngay cả khi chỉ có một ảnh. Mỗi ảnh tối đa 30 MB, chiều rộng và chiều cao tối thiểu 300 px, với tỷ lệ rộng/cao từ 0.4 đến 2.5.
Giữ chủ thể nhất quán với kling_elements
Một element là một nhân vật hoặc vật thể được thể hiện từ 2 đến 4 góc nhìn, góc chính diện đặt đầu tiên. Element cần ít nhất một mục image_urls, và bạn có thể truyền tối đa 7 element; tổng số ảnh cộng element tối đa là 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"
}
}
Request này tốn 13 credit cho ảnh 2K cộng 1 cho ảnh tham chiếu và 1 cho element: 15 credit ($0.075).
Bộ ảnh với enable_sequential
Với enable_sequential: true, n nằm trong khoảng 2 đến 10 (mặc định 4) và mô hình lên kế hoạch các ảnh như một bộ với cùng chủ thể và phong cách, trả về theo thứ tự. Khi tắt, n từ 1 đến 9 trả về các ảnh độc lập.
{
"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
}
}
Trong thử nghiệm ngày ra mắt của chúng tôi (API production của PoYo, ngày 19 tháng 11 năm 2026), một bộ 16:9, 2K với n: 4 trả về bốn ảnh 2720×1536 với cùng người lái, xe đạp và trang phục qua bình minh, giữa trưa, hoàng hôn và ban đêm. Bộ ảnh có giá 52 credit và mất khoảng 4.9 phút từ lúc submit đến khi có kết quả.
Trang webpage và ecommerce dạng dài
Đổi model ID sang kling-4.0-long-image và chọn một skill. Một thiết kế webpage, có thể theo ảnh tham chiếu phong cách:
{
"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"
}
}
Một trang chi tiết ecommerce từ một ảnh sản phẩm:
{
"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"
}
}
Mẹo: nêu rõ ngôn ngữ của trang. Trong thử nghiệm của chúng tôi, một prompt webpage bằng tiếng Anh không nói nội dung trang dùng ngôn ngữ gì lại trả về chữ tiếng Trung trên trang. Thêm câu "All text on the page is in English." vào prompt đã khắc phục được, vì thế cả hai body ở trên đều kết thúc bằng câu đó. Thử nghiệm webpage 1K của chúng tôi trả về một ảnh 1024×4257 với giá 110 credit trong khoảng 1.7–2.2 phút.
image_urls và length thuộc về ecommerce; style_image_url và subject_image_url thuộc về webpage. Chi tiết về độ dài trang và đầu ra 8K có trong ảnh 8K và long image với Kling Image 4.0 API.
Lưu kết quả
Mỗi files[].file_url trỏ đến một file PNG. Hãy sao chép về storage của bạn thay vì hot-link trực tiếp từ ứng dụng. Ba điều từ lần chạy ngày ra mắt cần lưu ý:
- Dung lượng. Một ảnh 16:9 8K là file PNG 10880×6144 khoảng 128 MB. Hãy stream xuống đĩa thay vì tải vào bộ nhớ, và tăng read timeout của client.
- Kênh alpha. File tải về là PNG RGBA ngay cả với ảnh không trong suốt. Nếu pipeline, CDN hoặc quy trình in của bạn cần RGB hoặc JPEG, hãy chuyển đổi sau khi tải về.
- Thứ tự. Bộ ảnh được trả về theo thứ tự, nên chỉ số trong
fileschính là số khung hình của storyboard hoặc bộ slide.
Các quy tắc xác thực nên kiểm tra trước khi submit
| Quy tắc | Mô hình |
|---|---|
prompt 1–50,000 ký tự, không chỉ toàn khoảng trắng | cả hai |
image_urls 1–10 mục; mỗi ảnh 30 MB, ≥300 px, tỷ lệ 0.4–2.5 | kling-4.0-image |
kling_elements ≤ 7, mỗi element 2–4 URL, chỉ dùng cùng image_urls; ảnh + element ≤ 10 | kling-4.0-image |
n 1–9 khi không dùng bộ ảnh, 2–10 khi có enable_sequential: true | kling-4.0-image |
resolution 2K / 4K / 8K | kling-4.0-image |
skill: "ecommerce" cần 1–3 image_urls; resolution 1K / 2K | kling-4.0-long-image |
Không có trường thừa (output_format, seed, negative_prompt bị từ chối) | cả hai |
Các lỗi nên xử lý
code | Ý nghĩa | Cách xử lý |
|---|---|---|
| 400 | Tham số không hợp lệ | Sửa body; đừng thử lại khi chưa thay đổi gì |
| 401 | Thiếu hoặc sai API key | Kiểm tra header |
| 402 | Không đủ credit | Nạp thêm rồi submit lại |
| 429 | Vượt giới hạn tốc độ | Chờ và thử lại sau |
| 500 / 502 / 503 | Lỗi server hoặc upstream | Thử submit lại với backoff |
Task failed không bị tính phí, nên submit lại sau khi thất bại là an toàn. Submit lại sau khi phía bạn bị timeout thì không: hãy polling cùng task_id trước.
Cách tính hóa đơn đầu tiên của bạn
kling-4.0-image tính giá mỗi ảnh nhân với số ảnh, cộng 1 credit cho mỗi mục image_urls và mỗi element, tính một lần mỗi request. Với 1 credit = $0.005:
| Request | Credit | USD |
|---|---|---|
| Lệnh cURL đầu tiên ở trên (2K, một ảnh) | 13 | $0.065 |
| Cùng prompt ở 8K | 32 | $0.16 |
| Chỉnh sửa với element ở trên (2K, 1 ảnh + 1 element) | 15 | $0.075 |
| Bộ bốn ảnh 2K | 52 | $0.26 |
| Webpage 1K, không có tham chiếu | 110 | $0.55 |
| Trang ecommerce medium 1K, 1 ảnh sản phẩm | 95 | $0.475 |
Bảng đầy đủ và thêm ví dụ có trong giá Kling Image 4.0 API. Để xem tổng quan về cả hai model ID, hãy đọc Kling Image 4.0 là gì.
Câu hỏi thường gặp
Làm thế nào để gọi Kling Image 4.0 API bằng Python?
POST body JSON tới https://api.poyo.ai/api/generate/submit bằng requests, đọc data.task_id, rồi polling /api/generate/status/{task_id} cho đến khi finished và đọc files[].file_url. Vòng lặp ở trên làm việc này với giới hạn thời gian và kiểm tra lỗi.
Model ID của Kling Image 4.0 API là gì?
kling-4.0-image cho text-to-image, chỉnh sửa và bộ ảnh, và kling-4.0-long-image cho trang webpage và ecommerce dạng dài. kling-4-0-image chỉ là slug của trang.
Kling Image 4.0 API có hỗ trợ webhook không?
Có. Thêm callback_url ở cấp ngoài cùng của request. PoYo gửi một POST có chữ ký khi task hoàn tất hoặc thất bại.
Tôi có thể nhận đầu ra JPEG từ Kling Image 4.0 API không? Không có trường định dạng đầu ra; kết quả là PNG. File chúng tôi tải về là PNG RGBA ngay cả với ảnh không trong suốt, nên hãy tự chuyển đổi nếu bạn cần JPEG.
Tại sao long webpage Kling Image 4.0 của tôi lại ra ngôn ngữ khác? Nếu prompt không nêu ngôn ngữ cho nội dung trang, mô hình có thể tự chọn. Hãy nêu rõ, ví dụ "All text on the page is in English."