Bắt đầu

Mọi request gửi và nhận JSON. Phản hồi luôn có trường ok; khi lỗi có thêm error mô tả bằng tiếng Việt.

Base URL

http://localhost:3000

Xác thực

Gửi API key ở header của mọi request. Chấp nhận cả hai kiểu — dùng kiểu nào tool của bạn hỗ trợ.

X-API-Key: vk_xxxxx

# hoac, neu tool cua ban chi co o "Bearer token":
Authorization: Bearer vk_xxxxx

Credit

Credit bị trừ ngay khi tạo job. Nếu tạo thất bại vì lỗi hệ thống, credit được hoàn lại tự động. Xem bảng giá chi tiết từng model, hoặc gọi GET /api/v1/models để lấy bảng giá theo thời gian thực thay vì ghi cứng số trong code.

Tạo video

POST/api/v1/videos

Tham số

Ví dụ

curl -X POST http://localhost:3000/api/v1/videos \
  -H "X-API-Key: vk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Chú mèo phi hành gia trôi trong vũ trụ, ánh sáng rực rỡ",
    "duration": 10,
    "ratio": "9:16"
  }'

Phản hồi

{
  "ok": true,
  "video": {
    "id": "cms8rhkln0001vne0gfseyy7x",
    "status": "queued",
    "prompt": "Chú mèo phi hành gia...",
    "duration": 10,
    "ratio": "9:16",
    "credit_cost": 10000,
    "video_url": null,
    "error": null,
    "created_at": "2026-07-31T09:50:14.411Z",
    "done_at": null
  },
  "balance": 458000
}

Chọn model

GET/api/v1/models

Không gửi model thì hệ thống dùng cấu hình mặc định. Muốn chọn cụ thể thì lấy danh sách ở đây — đừng ghi cứng vào code, kho model đổi theo thời gian.

{
  "ok": true,
  "servers": [{
    "id": 2,
    "name": "Máy chủ chính",
    "models": [{
      "model": "kling_video_3_0",
      "name": "Kling AI 3.0",
      "media_type": "video",
      "durations_avail": ["5", "10"],
      "resolutions_avail": [],
      "credit_cost_matrix": { "5||standard": 5, "10||standard": 10 },
      "price_combos": ["5||standard", "10||standard"],
      "requires": null
    }]
  }]
}

Đọc bảng giá của một model

Khoá trong credit_cost_matrix có dạng duration|resolution|mode — phần nào model không dùng thì để trống. Giá trị chính là số credit sẽ bị trừ.

Kho model đi theo nhà cung cấp: model nào đang bán được thì có trong danh sách này. Vì vậy hãy gọi lại định kỳ thay vì lưu một bản chép cứng.

Kiểm tra kết quả

GET/api/v1/videos/{id}

Hỏi lại mỗi 15–30 giây. Khi status là done thì video_url có link tải.

curl http://localhost:3000/api/v1/videos/cms8rhkln0001vne0gfseyy7x \
  -H "X-API-Key: vk_xxxxx"

Trạng thái

Webhook — khỏi phải hỏi lại

Thêm callback_url khi tạo job, hệ thống sẽ gọi về địa chỉ đó ngay khi xong. Một video 30 phút mà hỏi lại mỗi 20 giây là ~90 request rỗng; có webhook thì còn đúng một.

curl -X POST http://localhost:3000/api/v1/videos \
  -H "Authorization: Bearer vk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Chú mèo phi hành gia",
    "duration": 10,
    "callback_url": "https://server-cua-ban.com/webhook"
  }'

Hệ thống gửi về

POST https://server-cua-ban.com/webhook
X-Webhook-Timestamp: 1785600000
X-Webhook-Signature: sha256=a3f1...

{
  "event": "video.completed",
  "video": {
    "id": "cms...",
    "status": "done",
    "video_url": "https://...mp4",
    "credit_cost": 10000,
    "error": null
  }
}

Xác minh chữ ký

Ai biết địa chỉ webhook của bạn cũng gửi được thông báo giả. Hãy kiểm tra chữ ký trước khi tin. Lấy khoá bí mật ở trang chính, mục Webhook.

// Node.js
const crypto = require('crypto')

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const ts  = req.headers['x-webhook-timestamp']
  const sig = req.headers['x-webhook-signature']
  const body = req.body.toString()

  const mong = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(ts + '.' + body)
    .digest('hex')

  if (sig !== mong) return res.status(401).end()
  // Quá 5 phút thì bỏ — chặn phát lại request cũ
  if (Math.abs(Date.now()/1000 - Number(ts)) > 300) return res.status(401).end()

  const data = JSON.parse(body)
  console.log('xong:', data.video.video_url)
  res.status(200).end()   // trả 200, nếu không hệ thống sẽ gửi lại
})

Địa chỉ phải dùng https và trỏ ra Internet công cộng. Địa chỉ nội bộ (localhost, 10.x, 192.168.x…) bị từ chối vì lý do bảo mật.

Dùng qua lớp tương thích thì đặt tên trường theo nhà đó: fal_webhook (query, fal.ai), callBackUrl (kie.ai), config.webhook_config.endpoint (PiAPI).

Ảnh tham chiếu

POST/api/v1/upload-image

Gửi multipart/form-data, field tên image. Nhận png/jpg/webp, tối đa 10MB. Bước này không tốn credit.

# 1) Tải ảnh lên
curl -X POST http://localhost:3000/api/v1/upload-image \
  -H "X-API-Key: vk_xxxxx" \
  -F "image=@nhan-vat.png"
# → { "ok": true, "image_url": "https://..." }

# 2) Tạo video từ ảnh đó
curl -X POST http://localhost:3000/api/v1/videos \
  -H "X-API-Key: vk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Nhân vật vẫy tay chào, camera zoom nhẹ","image_url":"https://..."}'

Viết kịch bản

POST/api/v1/chat/completions

Đúng chuẩn OpenAI — tool nào nói được với OpenAI thì chỉ cần đổi Base URL sang địa chỉ này, không phải sửa gì thêm.

curl -X POST http://localhost:3000/api/v1/chat/completions   -H "X-API-Key: vk_xxxxx"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "Viết kịch bản video 15 giây quảng cáo quán tạp hoá"}
    ],
    "max_tokens": 1000
  }'

Model dùng được: gpt-5.5 và claude-opus-4-8. Trả về đúng hình dạng choices[0].message.content và usage như OpenAI, kèm hai trường thêm credit_cost và balance để bạn biết vừa tiêu bao nhiêu mà khỏi gọi thêm request.

Bóc lời từ audio

POST/api/v1/audio/transcriptions

Gửi multipart/form-data. Cũng theo chuẩn OpenAI.

# Cach 1 — gui thang file (chi hop voi file nho)
curl -X POST http://localhost:3000/api/v1/audio/transcriptions   -H "X-API-Key: vk_xxxxx"   -F "file=@ghi-am.mp3"

# Cach 2 — dua dia chi, he thong tu tai ve
curl -X POST http://localhost:3000/api/v1/audio/transcriptions   -H "X-API-Key: vk_xxxxx"   -F "file_url=https://server-cua-ban.com/ghi-am.mp3"

Trả về text (nội dung), duration (số giây), credit_cost và balance.

Hỏi giá trước khi làm

POST/api/v1/estimate

Trả về số credit sẽ bị trừ mà không trừ đồng nào. Gọi cái này trước khi tạo job thì tool của bạn biết trước chi phí, và biết cả lựa chọn rẻ hơn.

curl -X POST http://localhost:3000/api/v1/estimate   -H "X-API-Key: vk_xxxxx"   -H "Content-Type: application/json"   -d '{"kind":"image","model":"google_image_gen_banana_pro"}'

{
  "ok": true,
  "credit_cost": 7000,
  "vnd": 7000,
  "balance": 124374,
  "du_credit": true,
  "re_hon": [
    { "model": "gemini-3.0-pro-image-portrait", "name": "Gemini 3.0 Pro — Ảnh dọc", "tu_khoang": "28 credit" },
    { "model": "gpt-image-2", "name": "GPT Image 2", "tu_khoang": "500 credit" }
  ]
}

Sửa ảnh · Tách nền · Ghép ảnh

POST/api/v1/images/edits

Gửi multipart/form-data với file ảnh đính kèm, đúng chuẩn OpenAI. Khác với /api/v1/images ở chỗ nhận thẳng file thay vì bắt bạn tự đưa ảnh lên đâu đó lấy địa chỉ.

# Tach nen, giu nguyen chu tren bao bi
curl -X POST http://localhost:3000/api/v1/images/edits   -H "X-API-Key: vk_xxxxx"   -F "image=@san-pham.png"   -F "prompt=Tach nen, giu nguyen chu the va chu tren bao bi"   -F "background=transparent"

# Ghep hai anh — dua ca hai vao cung luc
curl -X POST http://localhost:3000/api/v1/images/edits   -H "X-API-Key: vk_xxxxx"   -F "image[]=@san-pham.png"   -F "image[]=@nhan-vat.png"   -F "prompt=Nhan vat cam san pham tren tay"

Phản hồi trả về job giống /api/v1/images, kèm input_urls — địa chỉ ảnh bạn vừa gửi, dùng lại được cho lần sau mà không phải tải lên nữa.

Các endpoint khác

Dùng key trong tool có sẵn

Nếu tool của bạn không cho điền API tuỳ ý mà chỉ hỗ trợ một số nhà cung cấp, hãy chọn nhà tương ứng bên dưới rồi đổi Base URL sang địa chỉ ở cột giữa. Key vẫn là key của bạn, credit vẫn trừ trong cùng một ví.

Lớp tương thích chỉ đổi hình dạng request. Giá, hạn mức và cách trừ credit hoàn toàn giống khi gọi /api/v1 trực tiếp.

Mã lỗi