Chuyển đến nội dung chính
OrcaRouter giao tiếp bản địa với Kling để tạo video. Bạn gửi một task, poll task ID để biết trạng thái, và lấy file MP4 đã render khi upstream hoàn tất (thường 30 - 90 giây). Mẫu submit-rồi-poll bất đồng bộ này là duy nhất với video. Chat / hình ảnh / TTS đều dùng request-response đồng bộ; video Kling thì không.
Endpoint submit POST /v1/video/generations được chia sẻ giữa các nhà cung cấp video — hình dạng thân yêu cầu được chọn theo tiền tố model của bạn. Trang này bao phủ model: kling/.... Với các mô hình ByteDance Seedance dùng model: byteplus/... và làm theo Seedance Video. Endpoint fetch GET /v1/video/generations/{task_id} giống nhau cho cả hai.

​
Mô hình

Tất cả mô hình đều hỗ trợ text-to-video và image-to-video. Các tính năng nâng cao thì khác nhau:
Mô hìnhRef đa nguồn¹4KÂm thanh bản địa²Đa cảnh
kling/kling-v2-master
kling/kling-v2-1-master
kling/kling-v2-5-turbo
kling/kling-v2-6chế độ pro
kling/kling-v3✓✓✓
kling/kling-video-o1✓ (giới hạn)
kling/kling-v3-omni✓ (đầy đủ)✓✓✓
¹ Ref đa nguồn = các trường metadata image_list / video_list. Định tuyến đến endpoint Omni-Video của Kling khi có. kling/kling-video-o1 là một tập con bị giới hạn (chỉ 5s/10s, không đa cảnh, không âm thanh); chọn kling/kling-v3-omni cho bề mặt Omni đầy đủ. ² Âm thanh bản địa = Kling tự sinh nhạc nền khớp với video. Tính phí thêm phía upstream. Bật/tắt qua metadata.sound: "on". Endpoint submit giống nhau cho mọi mô hình — POST /v1/video/generations. Khác biệt nằm ở việc upstream tôn trọng các trường metadata nào theo bảng trên.

​
Gửi một task

Gửi POST đến /v1/video/generations với model, prompt và bất kỳ tham số nào riêng của upstream dưới metadata: 
curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "cat playing piano in a sunny room",
    "metadata": {
      "mode": "std",
      "aspect_ratio": "16:9",
      "duration": "5"
    }
  }'
Phản hồi chứa task ID: 
{
  "id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "object": "video",
  "model": "kling/kling-v3-omni",
  "status": "queued",
  "progress": 0,
  "created_at": 1777975188
}
POST trả về status: "queued" chữ thường. GET trả về một envelope đã bọc với status chữ hoa (SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE) — xem mục Poll kết quả bên dưới.

​
Các trường metadata phổ biến

Ba trường này áp dụng cho mọi biến thể endpoint:
TrườngKiểuGhi chú
modestringstd (720P) / pro (1080P) / 4k. 4k chỉ trên kling/kling-v3 và kling/kling-v3-omni. Mặc định là std cho text/image-to-video, pro cho Omni-Video.
aspect_ratiostring16:9 / 9:16 / 1:1. Bắt buộc trên Omni-Video trừ khi bạn cung cấp ảnh tham chiếu khung đầu hoặc video_list (trong các trường hợp đó nó được suy ra từ đầu vào).
durationstringĐộ dài tính bằng giây. Mặc định "5". kling/kling-v3-omni và kling/kling-v3 chấp nhận "3" đến "15". Họ v2 (v2-master, v2-1-master, v2-5-turbo, v2-6) và kling/kling-video-o1 chấp nhận "5" hoặc "10". Xem Bản đồ khả năng Kling cho dải chính thức theo từng mô hình.
Hai trường này chỉ hoạt động trên text-to-video và image-to-video (không phải Omni-Video):
TrườngKiểuGhi chú
negative_promptstringNhững thứ cần tránh. Tối đa 2500 ký tự.
cfg_scalefloatKhoảng [0, 1], mặc định 0.5. Cao hơn = bám sát prompt nghiêm ngặt hơn. Không hỗ trợ trên các mô hình v2.x (kling-v2-master / v2-1-master / v2-5-turbo / v2-6).

​
Poll kết quả

Dùng task ID được trả về khi submit: 
curl https://api.orcarouter.ai/v1/video/generations/task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw \
  -H "Authorization: Bearer sk-orca-..."
Hình dạng phản hồi được bọc: 
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://v16-kling-fdl.klingai.com/.../video.mp4?...",
    "action": "omniVideo",
    "submit_time": 1777975188,
    "start_time": 1777975241,
    "finish_time": 1777975277,
    "fail_reason": ""
  }
}
Các giá trị status (chữ hoa, trạng thái task thô):
StatusÝ nghĩa
NOT_STARTDòng task đã tạo, chưa được dispatch (thoáng qua, thường dưới 2s)
SUBMITTEDĐã gửi đến upstream Kling, đang chờ trong hàng đợi của họ
IN_PROGRESSKling đang render
SUCCESSXong. data.result_url mang file MP4
FAILUREThất bại. data.fail_reason có lý do
Tiến độ trả về dưới dạng chuỗi phần trăm ("30%", "100%"), không phải số nguyên. Poll mỗi 5 - 10 giây. Một clip std 5 giây điển hình hoàn tất trong 30 - 60 giây; các task 4K, 15 giây và đa cảnh mất 2 - 5 phút. data.result_url là URL được Kling ký (chú ý các tham số truy vấn ksTime / ksSecret). Hãy tải xuống hoặc host lại nhanh chóng nếu bạn cần lưu giữ lâu — chữ ký có thời gian hết hạn do upstream xác định.

​
Biến thể endpoint

Cả ba biến thể đều chia sẻ POST /v1/video/generations. Endpoint mà Kling thực sự phục vụ được xác định bởi các trường bạn cung cấp.

​
Text-to-video

Chỉ model + prompt (+ metadata tùy chọn ở trên). Không có đầu vào hình ảnh nghĩa là text-to-video: 
curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-6",
    "prompt": "ocean waves at sunset, cinematic",
    "metadata": {"mode": "pro", "duration": "5"}
  }'

​
Image-to-video

Thêm image ở cấp cao nhất (khung đầu) và / hoặc metadata.image_tail (khung cuối) để làm i2v khung đầu / khung cuối: 
curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-master",
    "prompt": "the cat starts dancing",
    "image": "https://example.com/cat.png",
    "metadata": {"mode": "std", "duration": "5"}
  }'

​
Tham chiếu đa nguồn (Omni-Video)

image_list và video_list định tuyến yêu cầu đến endpoint Omni-Video của Kling. Chỉ có trên kling/kling-video-o1 và kling/kling-v3-omni. image_list — tham chiếu nhiều ảnh: 
{ "image_list": [{ "image_url": "...", "type": "first_frame" }] }
  • image_url (bắt buộc): URL hoặc base64 thô (không có tiền tố data:).
  • type (tùy chọn): first_frame / end_frame. Bỏ qua trừ khi ảnh có ý nghĩa là một mỏ neo khung. Không hỗ trợ chỉ-end (luôn ghép với một ảnh khung đầu).
video_list — tham chiếu video (tối đa 1 video, MP4/MOV, ≤200MB): 
{ "video_list": [{ "video_url": "...", "refer_type": "base", "keep_original_sound": "yes" }] }
  • refer_type: base (chỉnh sửa video — video đầu vào được chỉnh sửa; mặc định) hoặc feature (tham chiếu phong cách/bố cục — sinh cảnh kế tiếp/trước đó).
  • keep_original_sound: yes / no.
  • Trên kling/kling-v3-omni, tham chiếu video chỉ được hỗ trợ ở duration 3-10s, chế độ std/pro (không phải 4K).
Khi video_list được đặt, metadata.sound phải là "off" — nếu không Kling sẽ từ chối tổ hợp đó.
Tham chiếu hình ảnh / video / thành phần bên trong prompt bằng cú pháp <<<>>>: <<<image_1>>>, <<<video_1>>>, <<<element_1>>>. Chỉ dành cho Omni. Chỉ số khớp với thứ tự trong mảng (bắt đầu từ 1). 
curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "<<<image_1>>> waves at the camera, then walks toward the ocean",
    "metadata": {
      "image_list": [{"image_url": "https://example.com/person.jpg"}],
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": "5",
      "sound": "on"
    }
  }'

​
Tính năng nâng cao

Các tính năng này hoạt động trên các endpoint text-to-video, image-to-video và Omni-Video — hỗ trợ theo mô hình thì khác nhau. Truyền chúng qua metadata.

​
Đa cảnh

Tạo một video gồm nhiều cảnh tuần tự, mỗi cảnh có prompt và duration riêng. Có trên kling/kling-v3 và kling/kling-v3-omni.
TrườngKiểuMục đích
multi_shotboolĐặt true để bật. Khi đó prompt cấp cao nhất và các đầu vào khung đầu/cuối bị bỏ qua.
shot_typestringcustomize (dùng multi_prompt nguyên văn) hoặc intelligence (Kling tự phân đoạn). Bắt buộc khi multi_shot=true.
multi_promptarray[{index, prompt, duration}]. 1 - 6 storyboard. duration của mỗi cảnh ≥ 1s; tổng phải bằng duration của cả task. Mỗi prompt ≤ 512 ký tự.

​
Âm thanh bản địa

Kling tự sinh nhạc nền khớp với video. Tính phí thêm phía upstream. Bật/tắt qua metadata.sound: "on" (mặc định "off"). Hỗ trợ theo mô hình:
  • kling/kling-v3 và kling/kling-v3-omni: mọi chế độ (std / pro / 4K)
  • kling/kling-v2-6: chỉ chế độ pro
  • Mọi mô hình khác: không hỗ trợ

​
Watermark

Truyền metadata.watermark_info: {enabled: true} để in watermark của Kling lên video đã render. Mặc định là không có watermark.

​
Tính phí

Video Kling tính phí theo task. OrcaRouter tính chính xác những gì Kling tính — final_unit_deduction của upstream trở thành khoản trừ ví, không phụ phí. Chi phí cuối cùng khớp với bảng giá đã công bố của Kling. Một khoản giữ trước nhỏ được dành ra tại thời điểm submit để bao phủ chi phí có khả năng cao nhất cho yêu cầu của bạn (ví dụ 4K + âm thanh); phần chênh được hoàn lại ngay khi task thành công. Xem lịch sử ví của bạn trong console để biết chi tiêu thực tế theo từng task.

​
Dùng SDK Kling trực tiếp

Nếu bạn đã có mã viết với SDK chính thức của Kling, OrcaRouter cũng giao tiếp được định dạng wire bản địa của Kling trên /kling/v1/videos/.... Các trường thân giữ phẳng (model_name, mode, v.v.) — chỉ base URL, header Authorization và giá trị model_name thay đổi: 
curl https://api.orcarouter.ai/kling/v1/videos/omni-video \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling/kling-v3-omni",
    "prompt": "cat playing piano",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "5",
    "sound": "on"
  }'
model_name phải dùng định danh mô hình phía OrcaRouter (cùng tên bạn dùng trên /v1/video/generations), không phải tên mô hình trần của Kling. OrcaRouter giải nó qua ánh xạ mô hình của kênh trước khi chuyển tiếp đến Kling.
Đường dẫn fetch tương ứng là GET /kling/v1/videos/omni-video/{task_id} (hoặc text2video, image2video). Chọn định dạng wire nào khớp với mã hiện có của bạn. Cả hai tính phí giống hệt nhau.

​
Xem thêm