Hướng dẫn Kling 4.0 API: Tạo video đầu tiên bằng Python và cURL

Kling 4.0 API trên PoYo dùng một model ID duy nhất, kling-4.0, cho tạo video từ văn bản, tạo video từ khung hình đầu/cuối, tham chiếu hình ảnh và chỉnh sửa video. Bạn gửi yêu cầu, lưu lại task ID rồi polling cho đến khi tác vụ hoàn tất. Hướng dẫn này bám theo schema hiện tại của PoYo, được kiểm tra vào ngày 24 tháng 10 năm 2026; tên trường của nhà cung cấp khác không dùng thay thế được.

Mở playground Kling 4.0 để thử các đầu vào trực quan, hoặc xem tài liệu API.

Tạo video đầu tiên bằng cURL

Đặt POYO_API_KEY trong biến môi trường của shell, rồi gửi yêu cầu năm giây dưới đây. Hãy giữ khóa trên máy chủ, đừng đưa vào mã chạy trên trình duyệt.

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",
    "input": {
      "prompt": "A paper boat floats beneath a stone bridge. One continuous low tracking shot, soft morning light, gentle water sounds, no speech or on-screen text.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Đọc data.task_id từ phản hồi JSON; gửi thành công chưa có nghĩa là video đã xong. Thay YOUR_TASK_ID bên dưới bằng giá trị đó:

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 được ghi trong tài liệu là not_started, running, finished và failed. Khi hoàn tất, kiểm tra data.files để lấy file_url của video. Nếu thất bại, xem error_message và giữ lại task ID để chẩn đoán. Polling một tác vụ đã có không cần gửi lại yêu cầu.

Vòng lặp polling có giới hạn bằng Python

Cài requests và chạy đoạn mã này ở backend. Nó kiểm tra cả lỗi HTTP lẫn lỗi ứng dụng, dừng khi tác vụ thất bại và giới hạn thời gian chờ ở 30 phút. Hết thời gian chờ nghĩa là bạn nên kiểm tra lại chính tác vụ đó sau; tự động gửi lại yêu cầu có thể tạo ra tác vụ tính phí thứ 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(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") not in (0, 200):
        raise RuntimeError(body.get("message") or "PoYo API error")
    return body["data"]

task = checked(session.post(base + "/api/generate/submit", json={
    "model": "kling-4.0",
    "input": {
        "prompt": "A paper boat floats beneath a stone bridge. Slow tracking shot.",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Task:", task_id, flush=True)
deadline = time.monotonic() + 1800
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":
        videos = [f["file_url"] for f in task.get("files", [])
                  if f.get("file_type") == "video"]
        if not videos:
            raise RuntimeError("Finished task returned no video")
        print(videos[0])
        break
    time.sleep(10)
else:
    raise TimeoutError("Check the saved task ID again: " + task_id)

Chọn đúng chế độ đầu vào

Trường video nguồn sẽ chọn chế độ chỉnh sửa ngay cả khi có kèm ảnh tham chiếu. Với ảnh thành video, ảnh đầu tiên xác lập khung hình mở đầu; ảnh thứ hai xác định khung hình kết thúc. Ảnh tham chiếu dẫn dắt nhận diện hoặc phong cách và không mang ý nghĩa giống khung hình biên.

Các giới hạn nên kiểm tra trước khi gửi

Chế độ tạo hỗ trợ thời lượng là số nguyên từ 3 đến 30 giây, ở 720p hoặc 1080p. Trong schema này của PoYo, prompt thông thường giới hạn 26.000 ký tự. Mỗi cảnh trong multi_prompt nhận tối đa 512 ký tự; nếu bỏ trống thời lượng cảnh, mặc định là năm giây. Tổng thời lượng các cảnh phải nằm trong 3–30 giây, và nếu khai báo thời lượng cấp cao nhất thì giá trị đó phải bằng tổng này.

Tham chiếu cho phép tối đa 10 ảnh, năm video và bảy chủ thể, trong giới hạn tổng cộng 15 tài nguyên. Khung hình đầu được tính vào cả giới hạn ảnh lẫn giới hạn tổng. Mỗi video tham chiếu hoặc video chủ thể phải dài 3–30 giây; tổng thời lượng thực của chúng không được vượt quá 30 giây. Đừng làm tròn xuống thời lượng để một đầu vào quá khổ lọt qua bước kiểm tra.

Hiểu hóa đơn đầu tiên

Một yêu cầu 720p dài năm giây không có video đầu vào tốn 142,5 tín dụng, tức $0.7125 theo tỷ lệ quy đổi niêm yết hiện tại. Video đầu vào làm thay đổi cả đơn giá lẫn thời lượng tính phí. Xem các ví dụ về giá trước khi ước tính quy trình dùng video tham chiếu hoặc chỉnh sửa.

Sản phẩm chính thức dành cho nhà sáng tạo quảng bá thêm các điều khiển khác, gồm nhiều keyframe. Schema của PoYo ở đây cung cấp tối đa hai khung hình biên và prompt theo từng cảnh; đừng gửi các trường tự đặt như keyframes, seed, negative_prompt hay generate_audio tới endpoint này. Để xem ví dụ chạy được, hãy đọc tiếp hướng dẫn viết prompt và hướng dẫn Omni Reference.

Câu hỏi thường gặp

Model ID của API có phải là kling-4-0 không? Không. Đó là slug của trang. Model ID trong yêu cầu là kling-4.0.

Tôi có thể yêu cầu 4K ở đây không? Endpoint PoYo này hiện chỉ chấp nhận 720p và 1080p. Hãy kiểm tra schema của nhà cung cấp thay vì sao chép thông số quảng bá của ứng dụng dành cho nhà sáng tạo.

Tôi có thể dùng callback không? Yêu cầu gửi hỗ trợ trường cấp cao nhất callback_url. Hãy tham khảo tài liệu hiện hành về cách xử lý callback; ví dụ polling ở trên không phụ thuộc vào nó.

Nên bắt đầu từ đâu? Trước tiên dùng một yêu cầu ngắn chỉ có văn bản, lưu task ID và kết quả, rồi thêm từng loại đầu vào một trong playground.