TL;DR Bạn có thể truy cập các mô hình video Kling được hỗ trợ thông qua CometAPI bằng tài khoản CometAPI và khóa API, thay vì phải hoàn tất quy trình onboard nhà phát triển Kling riêng. Tuyến text-to-video hiện tại là POST /kling/v1/videos/text2video. Tuyến này trả về một task ID, backend của bạn sẽ thăm dò (poll) cho đến khi tác vụ đạt trạng thái succeed hoặc failed. Tính khả dụng của mô hình, tham số, giá và điều kiện tài khoản có thể thay đổi, vì vậy hãy xác minh danh mục mô hình đang hoạt động và tài liệu API trước khi triển khai production.
Câu trả lời trực tiếp
Lộ trình thực tế là Danh mục mô hình Kling của CometAPI. Nếu mô hình Kling bạn cần khả dụng cho tài khoản CometAPI của bạn, máy chủ có thể xác thực bằng khóa API của CometAPI và gọi endpoint tương thích Kling tương ứng. Với lộ trình này, không cần một ứng dụng API Kling riêng trong bước tích hợp.
Sự khác biệt này quan trọng với các đội vốn đã dùng CometAPI cho những mô hình khác. Ứng dụng chỉ cần một bề mặt quản lý thông tin xác thực và một quan hệ nhà cung cấp, đồng thời bổ sung thêm workflow video Kling. Mã của bạn vẫn phải sử dụng schema yêu cầu dành riêng cho video của Kling và vòng đời tác vụ bất đồng bộ; “một khóa API” không có nghĩa mọi nhà cung cấp dùng chung một body yêu cầu giống hệt nhau.
Bài viết này tập trung vào text-to-video vì đây là tích hợp nhỏ nhất nhưng hữu ích. CometAPI cũng có tài liệu cho image-to-video và các workflow Kling khác, mỗi loại có endpoint và ràng buộc tham số riêng. Hãy bắt đầu với một đường đi đã được xác minh, rồi chỉ bổ sung năng lực sau khi kiểm tra tài liệu hiện tại.
Vì sao lộ trình này hữu ích cho đội phát triển
Lợi ích trước mắt mang tính vận hành hơn là “kỳ diệu”. Một đội đã dùng CometAPI có thể thêm một workflow Kling sẵn có mà không cần tạo tích hợp trực tiếp với nhà cung cấp khác, phân phối thêm thông tin xác thực, hay xây dựng luồng quản lý tài khoản riêng. Điều đó có thể giảm số lượng bí mật, quan hệ thanh toán, và cấu hình client đặc thù nhà cung cấp mà nền tảng của bạn phải duy trì.
Lợi ích thứ hai mang tính kiến trúc. Ứng dụng của bạn có thể phơi bày một hợp đồng nội bộ tối giản cho việc tạo video—prompt, workflow, model, tùy chọn và trạng thái job—trong khi một adapter nhà cung cấp chuyển đổi hợp đồng đó thành yêu cầu Kling được tài liệu hóa. Nếu sau này đội đánh giá một mô hình video khác, mô hình job hướng sản phẩm vẫn có thể ổn định dù đường dẫn endpoint, tham số và siêu dữ liệu đầu ra khác nhau.
Giới hạn cũng quan trọng không kém: một lớp truy cập hợp nhất không khiến các mô hình nền tảng thay thế được cho nhau. Hành vi prompt, media chấp nhận, độ trễ, giá, chính sách an toàn và schema kết quả có thể khác nhau. Hãy giữ các khác biệt đó hiển thị rõ trong cấu hình và kiểm thử thay vì ẩn sau những giả định không được hỗ trợ.
Những gì lộ trình truy cập này thay đổi—và những gì không
Những gì thay đổi. Bạn tạo và quản lý khóa CometAPI, gửi yêu cầu tới API tương thích Kling của CometAPI, và theo dõi mức sử dụng từ phía CometAPI. Điều này loại bỏ bước onboard trực tiếp với Kling trong lộ trình truy cập cụ thể này.
Những gì không thay đổi. Kling vẫn là họ mô hình nền tảng. Các tham số đặc thù nhà cung cấp, hành vi sinh nội dung, quy tắc sử dụng chấp nhận được, tính khả dụng mô hình và đặc tính đầu ra vẫn quan trọng. Tài liệu của CometAPI cũng lưu ý rằng các trường yêu cầu và phản hồi có thể khác nhau theo nhà cung cấp, vì vậy hãy coi tham chiếu endpoint đang hoạt động là “hợp đồng” cho phần triển khai của bạn.
Những gì cần xác minh trước khi cam kết. Xác nhận tài khoản của bạn có thể truy cập model ID cần thiết, xem lại giá và giới hạn tốc độ hiện tại, và chạy một thử nghiệm nhỏ đã xác thực. Đừng thiết kế workflow production dựa trên tên mô hình lấy từ một bài blog cũ hoặc ví dụ đã được cache.
Trước khi bắt đầu
Bạn cần tài khoản CometAPI, một khóa API được lưu trên máy chủ, và một backend có khả năng chạy job bất đồng bộ. Giữ khóa trong biến môi trường như COMETAPI_KEY; đừng phơi bày khóa trong mã trình duyệt hay ứng dụng di động.
- Mở danh mục mô hình Kling và xác nhận mô hình bạn định dùng hiện đang được liệt kê cho tài khoản của bạn.
- Xem tài liệu Kling text-to-video API hiện tại. Tại thời điểm xác minh, ví dụ được tài liệu hóa dùng
kling-v3. - Tạo khóa API phía máy chủ trong bảng điều khiển CometAPI và đặt nó trong môi trường runtime của bạn.
- Quyết định nơi dịch vụ của bạn sẽ lưu trữ task ID và video cuối cùng. Yêu cầu tạo chỉ trả về một tác vụ, không phải tệp video đã hoàn tất.
Chọn workflow Kling trước khi thiết kế request
Bắt đầu từ tài sản mà sản phẩm của bạn hiện có. Nếu người dùng chỉ có mô tả bằng chữ, text-to-video là đường đi trực tiếp. Nếu người dùng có một ảnh tĩnh cần được giữ làm điểm tựa thị giác, hãy dùng tuyến image-to-video được tài liệu hóa riêng. Đừng thêm một trường ảnh vào yêu cầu text-to-video và cho rằng API sẽ suy ra workflow.
| Workflow | Đường tạo hiện tại | Dùng khi |
|---|---|---|
| Text to video | POST /kling/v1/videos/text2video | Đầu vào là một mô tả cảnh hoặc ý tưởng chuyển động bằng chữ và không cần bảo toàn ảnh nguồn. |
| Image to video | POST /kling/v1/videos/image2video | Đầu vào gồm một ảnh nguồn nhằm dẫn dắt chuyển động được tạo và bản sắc thị giác cần được bảo toàn. |
Tài liệu image-to-video hiện tại chấp nhận URL ảnh công khai hoặc chuỗi ảnh base64 và trả về một tác vụ bất đồng bộ. Các workflow Kling chuyên biệt hơn có trang riêng và ràng buộc yêu cầu riêng. Chỉ thêm từng cái một khi yêu cầu sản phẩm và tài liệu hiện tại biện minh cho adapter bổ sung.
Cho bản dựng production đầu tiên, hãy dùng một workflow, một model ID đã được xác minh, thời lượng ngắn, và một tập nhỏ các prompt đại diện. Cách này cô lập việc truy cập tài khoản và điều phối tác vụ khỏi việc đánh giá chủ quan đầu ra. Khi pipeline đã ổn định, hãy so sánh chế độ hoặc mô hình với một bộ đánh giá cố định thay vì thay đổi nhiều biến trong cùng một lần thử.
Tạo request text-to-video Kling đầu tiên
Endpoint text-to-video hiện tại chấp nhận JSON và xác thực Bearer. Bắt đầu với một prompt ngắn và thời lượng nhỏ nhất được hỗ trợ. Yêu cầu sau chỉ dùng các trường xuất hiện trong tham chiếu CometAPI hiện tại:
curl https://api.cometapi.com/kling/v1/videos/text2video \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off"
}'
Gửi thành công sẽ trả về một đối tượng chứa data.task_id và trạng thái tác vụ. Lưu task ID đó cùng bản ghi job của ứng dụng. Không giữ kết nối HTTP mở trong khi video đang render.
| Trường | Giá trị được tài liệu hóa | Ghi chú triển khai |
|---|---|---|
| model_name | Enum hiện có gồm kling-v3 và các nhánh trước đó | Xác nhận enum đang hoạt động và khả dụng tài khoản trước khi triển khai. |
| duration | 5 hoặc 10 | Bắt đầu với 5 giây để xác thực workflow. |
| aspect_ratio | 16:9, 9:16, 1:1 | Chỉ bỏ qua nếu mặc định được tài liệu hóa phù hợp bề mặt phân phối. |
| mode | std hoặc pro | Tài liệu mô tả pro là chất lượng cao hơn và chi phí cao hơn. |
| sound | on hoặc off | Chỉ áp dụng cho các nhánh mô hình hỗ trợ âm thanh tạo sinh. |
Xử lý tác vụ bất đồng bộ một cách an toàn
Việc tạo video Kling là bất đồng bộ. Với text-to-video, hãy poll GET /kling/v1/videos/text2video/{task_id}. Tài liệu tác vụ của CometAPI cho biết phản hồi có thể trả task trực tiếp hoặc bên trong lớp data, vì vậy ví dụ sẽ chuẩn hóa cả hai dạng. Đồng thời coi mọi trạng thái không kết thúc là “tiếp tục chờ”, thay vì giả định một danh sách cố định các trạng thái trung gian.
import os
import time
import requests
API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(prompt: str) -> str:
response = requests.post(
BASE_URL,
headers=HEADERS,
json={
"prompt": prompt,
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off",
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
return payload["data"]["task_id"]
def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
deadline = time.monotonic() + timeout_seconds
poll_url = f"{BASE_URL}/{task_id}"
while time.monotonic() < deadline:
response = requests.get(poll_url, headers=HEADERS, timeout=30)
response.raise_for_status()
payload = response.json()
task = payload.get("data") or payload
status = task.get("task_status")
if status == "succeed":
videos = task.get("task_result", {}).get("videos", [])
if not videos or not videos[0].get("url"):
raise RuntimeError("Task succeeded without a video URL")
return videos[0]["url"]
if status == "failed":
detail = task.get("task_status_msg") or task.get("task_result")
raise RuntimeError(f"Kling task failed: {detail}")
time.sleep(10)
raise TimeoutError(f"Kling task {task_id} exceeded {timeout_seconds}s")
task_id = submit_video(
"A small ceramic cup on a wooden table, steam rising in soft morning light"
)
video_url = wait_for_video(task_id)
print(video_url)
Chuỗi trạng thái thành công kết thúc là succeed, không phải succeeded. Khi tác vụ hoàn tất, hãy sao chép tài sản đã tạo vào kho lưu trữ do bạn kiểm soát nếu sản phẩm của bạn cần giữ lại. Đừng coi URL phân phối của nhà cung cấp là lưu trữ vĩnh viễn của ứng dụng.
Với khối lượng lớn hơn, hãy dùng hàng đợi hoặc worker thay vì poll trong một web request. CometAPI cũng có tài liệu URL callback cho tác vụ Kling. Nếu dùng webhook, hãy xác thực và khử trùng lặp sự kiện callback, đồng thời giữ một phương án dự phòng bằng polling cho các lần giao không đến.
Thiết kế vòng đời job ứng dụng trước khi mở rộng
Hãy coi tác vụ nhà cung cấp là một phần của bản ghi job riêng của bạn. Lưu application job ID, workflow, mô hình yêu cầu, provider task ID, URL truy vấn, trạng thái hiện tại, thời điểm gửi, thời điểm poll gần nhất và vị trí đầu ra. Điều này mang lại cho đội hỗ trợ và vận hành đủ ngữ cảnh để điều tra một lần tạo bị lỗi hoặc chậm mà không phải lần theo log yêu cầu thô.
Đừng tạo lại yêu cầu chỉ vì client không nhận được phản hồi. Nhà cung cấp có thể đã tạo tác vụ. Hãy lưu job cục bộ trước khi gửi, lưu task ID trả về ngay lập tức, và tách riêng việc thử lại tạo mới khỏi việc thử lại truy vấn trạng thái. Tham chiếu text-to-video hiện tại cũng có tài liệu external_task_id để theo dõi; hãy xác nhận hành vi thực tế trước khi dựa vào nó như một cơ chế khử trùng lặp.
const TERMINAL = new Set(["succeed", "failed"]);
function normalizeKlingTask(payload) {
const task = payload?.data ?? payload;
if (!task?.task_id || !task?.task_status) {
throw new Error("Kling response is missing task identity or status");
}
return task;
}
async function refreshVideoJob(job, apiKey) {
const response = await fetch(job.queryUrl, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) {
throw new Error(`Task query failed with HTTP ${response.status}`);
}
const task = normalizeKlingTask(await response.json());
const outputUrl = task.task_result?.videos?.[0]?.url ?? null;
return {
...job,
providerTaskId: task.task_id,
providerStatus: task.task_status,
terminal: TERMINAL.has(task.task_status),
outputUrl,
failureDetail: task.task_status_msg ?? null,
checkedAt: new Date().toISOString(),
};
}
Ví dụ này chủ ý không diễn giải mọi trạng thái trung gian có thể có của nhà cung cấp thành một cam kết hướng sản phẩm. Worker của bạn giữ các tác vụ chưa kết thúc ở trạng thái hoạt động, xử lý rõ ràng succeed và failed, và ghi lại trạng thái thô của nhà cung cấp để gỡ lỗi. Thêm một timeout phía ứng dụng để một tác vụ treo không tồn tại vô thời hạn.
Dùng polling làm tuyến cơ bản vì task ID luôn có thể truy vấn. Khi endpoint đã chọn hỗ trợ callback_url, webhook có thể giảm số lần yêu cầu trạng thái, nhưng không nên là cơ chế khôi phục duy nhất. Hướng dẫn chính thức về polling và webhook nêu rằng payload callback có thể đặc thù nhà cung cấp. Hãy lưu sự kiện thô, xử lý idempotent theo task ID, phản hồi HTTP thành công nhanh chóng, và đối soát trạng thái kết thúc bằng polling.
Danh sách kiểm tra production cho đội phát triển
- Xác thực mô hình khi runtime. Kiểm tra danh mục hiện tại và báo lỗi rõ ràng khi mô hình được yêu cầu không khả dụng. Đừng âm thầm thay thế bằng mô hình khác nếu hành vi đầu ra quan trọng.
- Tách biệt việc gửi và truy xuất. Lưu task ID của CometAPI, job ID của bạn, mô hình đã chọn và các mốc thời gian để việc thử lại không tạo công việc trùng lặp.
- Giới hạn polling. Dùng timeout, backoff lũy tiến hoặc khoảng thời gian cố định hợp lý, và số lần thử tối đa. Xem hướng dẫn giới hạn tốc độ và đồng thời của CometAPI trước khi tăng song song.
- Phân loại lỗi. Đừng thử lại với tham số không hợp lệ hoặc lỗi xác thực. Áp dụng backoff cho lỗi giới hạn tốc độ và lỗi nền tảng có thể thử lại, theo hướng dẫn mã lỗi và chiến lược thử lại hiện tại.
- Bảo vệ thông tin xác thực và đầu vào. Giữ khóa API phía máy chủ, tránh ghi log bí mật, và xác nhận người dùng có quyền với mọi prompt, ảnh hoặc tài sản nguồn họ gửi.
- Đo lường toàn bộ job. Theo dõi thành công gửi, thời gian xếp hàng, thời gian tạo, tỷ lệ lỗi kết thúc, tỷ lệ timeout, thành công truy xuất đầu ra và chi phí theo mô hình và chế độ.
- Lưu trữ đầu ra một cách có chủ đích. Tải về tài sản đã hoàn tất vào kho lưu trữ do bạn kiểm soát khi sản phẩm cần truy cập bền vững, rồi áp dụng chính sách lưu giữ và xóa.
Câu hỏi thường gặp thực tế
Tôi có cần tài khoản nhà phát triển Kling riêng cho lộ trình này không?
Không thấy có bước onboard nhà phát triển Kling riêng trong luồng tích hợp CometAPI. Bạn dùng tài khoản và khóa API CometAPI. Quyền truy cập vẫn phụ thuộc vào mô hình có khả dụng cho tài khoản và khu vực của bạn, vì vậy hãy xác nhận trước khi cam kết production.
API Kling có hoàn toàn tương thích OpenAI không?
Không đối với workflow video thể hiện ở đây. Nó dùng các tuyến dành riêng cho Kling như /kling/v1/videos/text2video và các trường đặc thù Kling. Bạn có thể quản lý thông tin xác thực qua CometAPI, nhưng adapter của bạn nên giữ schema đặc thù nhà cung cấp.
Tôi nên dùng model ID Kling nào?
Tham chiếu text-to-video hiện tại của CometAPI dùng kling-v3 trong ví dụ hoạt động đầu tiên và liệt kê vài nhánh trước đó. Hãy dùng model ID từ enum endpoint đang hoạt động và xác minh nó đã được bật cho tài khoản của bạn. Đừng giả định mô hình mới nhất khả dụng ở mọi nơi.
Tại sao phản hồi đầu tiên không chứa video?
Việc tạo video chạy dưới dạng tác vụ bất đồng bộ. Phản hồi ban đầu trả về task ID. Hãy poll tuyến truy vấn tương ứng cho đến khi task_status trở thành succeed hoặc failed, rồi đọc siêu dữ liệu kết quả.
Tôi nên poll hay dùng callback URL?
Polling dễ hơn cho tích hợp đầu tiên. Callback có thể giảm số lần yêu cầu ở quy mô lớn nhưng đòi hỏi trình nhận được xác thực, idempotent và logic khôi phục. Nhiều hệ thống production dùng callback như tuyến chính và polling như phương án dự phòng.
Tôi có thể dùng image-to-video qua cùng endpoint không?
Không. CometAPI tài liệu hóa image-to-video dưới tuyến riêng, /kling/v1/videos/image2video. Hãy làm theo schema yêu cầu hiện tại của endpoint đó thay vì thêm trường ảnh vào ví dụ text-to-video.
Nên bắt đầu với chế độ tiêu chuẩn hay chuyên nghiệp?
Dùng std để xác thực xác thực, hình dạng yêu cầu, lưu trữ tác vụ, polling và truy xuất đầu ra. Tài liệu hiện tại mô tả pro là chế độ chất lượng cao hơn, chi phí cao hơn. Hãy đánh giá nó với các prompt đại diện chỉ sau khi workflow cơ bản hoạt động, và so sánh chất lượng đầu ra cùng thời gian tạo và chi phí thực tế.
Làm sao tránh tạo trùng khi thử lại?
Tạo bản ghi job ứng dụng trước khi gọi API và lưu provider task ID trả về ngay lập tức. Thử lại truy vấn trạng thái độc lập với yêu cầu tạo. Đừng giả định lặp lại cùng một POST là idempotent. Endpoint hiện có tài liệu external_task_id để theo dõi, nhưng hãy xác minh ngữ nghĩa hiện hành trước khi coi đó là bảo đảm khử trùng lặp.
Kết luận
Đối với một nhóm phát triển tại Hoa Kỳ muốn thử tạo video Kling mà không cần hoàn tất đơn đăng ký nhà phát triển trực tiếp với Kling, CometAPI cung cấp một lộ trình đã được tài liệu hóa: xác minh mô hình Kling cần thiết khả dụng cho tài khoản, xác thực bằng khóa CometAPI, gọi endpoint đặc thù workflow, và theo dõi tác vụ bất đồng bộ đến trạng thái kết thúc.
Giá trị kỹ thuật thực tế là truy cập tập trung và một mô hình job ứng dụng có thể tái sử dụng—không phải giả định rằng mọi nhà cung cấp video hành xử giống nhau. Hãy giữ một adapter mỏng cho mỗi workflow, lưu trữ danh tính tác vụ và đầu ra một cách có chủ đích, và duy trì polling như một đường khôi phục ngay cả khi đã bật callback.
Một lộ trình triển khai an toàn là nhỏ và có thể đo lường: xác thực một mô hình và một workflow, gửi các job ngắn chi phí thấp, ghi nhận tỷ lệ thành công/thất bại kết thúc, xác minh truy xuất đầu ra, và so sánh chi phí cũng như độ trễ thực tế với yêu cầu sản phẩm. Chỉ mở rộng sang image-to-video hoặc các workflow Kling bổ sung sau khi tài liệu hiện tại và tài khoản mục tiêu của bạn đã được kiểm tra.