Tài liệu API — Pool API

Tài liệu API cho dev

Base URL: https://mark.klink.lol · Mọi request cần header Authorization: Bearer <API key>

POST 1. Tạo lượt mới `/api/jobs`

Content-Type: application/json

{
  "capability": "image | video | img2video | longvideo",
  "input": { "prompt": "Mô tả chi tiết thứ bạn muốn tạo" }
}

→ 202 {"job_id": "abc123..."}

GET 2. Xem trạng thái lượt `/api/jobs/<job_id>`

→ {"job_id": "...", "status": "queued | running | done | failed",
    "result": {"url": "https://...", "expires_at": "...", "bytes": 12345}}

Poll mỗi vài giây cho tới khi status là done hoặc failed. File kết quả tồn tại 48 giờ — hãy tải về sớm.

3. Các loại lượt

image — tạo 1 ảnh từ mô tả.
video — tạo video ~10 giây mỗi clip. Muốn video dài hơn trong 1 lượt: gửi input.clips (vd 3 → 3 clip ~10s ghép thành ~30s).
img2video — biến 1 ảnh thành video. Bắt buộc gửi URL ảnh trong input.image_url.
longvideo — video dài tới 60 giây. Gửi input.duration_sec (vd 45).

4. Tham số input chi tiết

Mọi tham số nằm trong object input:

Tham số	Áp dụng	Mô tả
`prompt`	Tất cả	Mô tả chi tiết thứ bạn muốn tạo. Bắt buộc.
`refs`	image, video, img2video	Ảnh tham chiếu (nhân vật, bối cảnh, phong cách). Danh sách tối đa 10 mục, mỗi mục là URL chuỗi hoặc object `{"name": "...", "url": "..."}` — tên không được trùng nhau trong 1 lượt. Ví dụ: `"refs": [{"name": "nhanvat-chinh", "url": "https://.../anh1.jpg"}, "https://.../anh2.jpg"]`
`image_url`	img2video	URL ảnh đầu vào để biến thành video. Bắt buộc với img2video.
`duration_sec`	longvideo	Thời lượng video mong muốn (giây), tối đa 60.
`clips`	video	Số clip ~10s ghép lại trong 1 lượt (mặc định 1).
`aspect`	video, img2video	Tỉ lệ khung hình yêu cầu, vd `"16:9"` hoặc `"9:16"`. File kết quả sai tỉ lệ sẽ bị từ chối để render lại.
`max_retries`	Tất cả	Số lần tự thử lại khi gặp lỗi tạm thời (0–5).

Ví dụ: tạo ảnh có ảnh tham chiếu nhân vật

POST /api/jobs
{
  "capability": "image",
  "input": {
    "prompt": "Chân dung cô gái trong vườn hoa anh đào, phong cách anime",
    "refs": [
      {"name": "nhanvat", "url": "https://example.com/nhanvat.jpg"}
    ]
  }
}

Ví dụ: img2video từ 1 ảnh có sẵn

POST /api/jobs
{
  "capability": "img2video",
  "input": {
    "prompt": "Mây trôi nhẹ, hoa rơi trong gió",
    "image_url": "https://example.com/phong-canh.jpg",
    "aspect": "16:9"
  }
}

5. Mã lỗi

400 — tham số không hợp lệ (vd refs quá 10 mục, tên ref trùng nhau, thiếu image_url cho img2video). Chi tiết trong error.
401 — sai hoặc thiếu API key.
402 package_expired — gói đã hết hạn (hoặc chưa có gói), cần mua/gia hạn.
429 concurrency_limit — đang dùng hết số luồng của gói, chờ lượt hiện tại xong rồi tạo tiếp.

Ví dụ (curl)

curl -s -X POST https://mark.klink.lol/api/jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capability":"image","input":{"prompt":"Mèo cam bên cửa sổ lúc hoàng hôn"}}'