how-tos

Hướng dẫn Kling Image 4.0 API: request đầu tiên với cURL và Python

Poyo.ai Team
10 min read
Share:

Hướng dẫn Kling Image 4.0 API: request đầu tiên với cURL và Python

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 files chí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ắcMô hình
prompt 1–50,000 ký tự, không chỉ toàn khoảng trắngcả hai
image_urls 1–10 mục; mỗi ảnh 30 MB, ≥300 px, tỷ lệ 0.4–2.5kling-4.0-image
kling_elements ≤ 7, mỗi element 2–4 URL, chỉ dùng cùng image_urls; ảnh + element ≤ 10kling-4.0-image
n 1–9 khi không dùng bộ ảnh, 2–10 khi có enable_sequential: truekling-4.0-image
resolution 2K / 4K / 8Kkling-4.0-image
skill: "ecommerce" cần 1–3 image_urls; resolution 1K / 2Kkling-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ĩaCách xử lý
400Tham số không hợp lệSửa body; đừng thử lại khi chưa thay đổi gì
401Thiếu hoặc sai API keyKiểm tra header
402Không đủ creditNạp thêm rồi submit lại
429Vượt giới hạn tốc độChờ và thử lại sau
500 / 502 / 503Lỗi server hoặc upstreamThử 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:

RequestCreditUSD
Lệnh cURL đầu tiên ở trên (2K, một ảnh)13$0.065
Cùng prompt ở 8K32$0.16
Chỉnh sửa với element ở trên (2K, 1 ảnh + 1 element)15$0.075
Bộ bốn ảnh 2K52$0.26
Webpage 1K, không có tham chiếu110$0.55
Trang ecommerce medium 1K, 1 ảnh sản phẩm95$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."

Share: