Tài liệu API

Địa chỉ gốc: https://lin-ai-video.hkdq.space. Tạo khoá ở trang API trong studio rồi gửi kèm mọi yêu cầu trong header Authorization:

curl https://lin-ai-video.hkdq.space/api/me \
  -H "Authorization: Bearer lin_KHOA_CUA_BAN"

• Khoá chỉ hiện một lần lúc tạo. Mất khoá thì thu hồi và tạo khoá mới; mỗi tài khoản có tối đa 5 khoá.
• Một khoá làm được mọi việc tài khoản làm được, kể cả trừ linh thạch. Đừng đưa khoá vào mã chạy trên trình duyệt hay kho mã công khai.
• Khoá không dùng được cho việc tạo, thu hồi khoá và các đường quản trị.

• Gửi và nhận JSON (trừ các đường tải file lên, dùng form nhiều phần).
• Lỗi trả mã HTTP từ 400 trở lên kèm { "error": "câu báo tiếng Việt", "code": "MÃ" }. Trường code có khi lỗi thuộc loại định sẵn.
• Các mã hay gặp: 401 khoá sai hoặc đã thu hồi; 402 không đủ linh thạch; 409 việc chưa làm được lúc này (cảnh đang dựng, nhân vật chưa có ảnh: CAST_NOT_READY); 422 kịch bản sai khuôn, kèm danh sách issues theo từng cảnh.
• Giới hạn tần suất cho mỗi tài khoản: đọc (GET) 120 lần mỗi phút, ghi (POST, PATCH, DELETE) 20 lần mỗi phút. Vượt mức trả 429 với "code": "RATE_LIMITED" và header Retry-After (số giây cần chờ). Gửi khoá sai nhiều lần liên tiếp thì bị chặn tạm một phút.
• Ba việc trừ linh thạch: viết kịch bản từ ý tưởng, gửi cảnh đi dựng và gửi video trending. Lượt lỗi được hoàn tự động.
• Việc dựng chạy nền. Hỏi lại trạng thái mỗi 5 đến 15 giây là đủ.

Gọi bằng khoá API, các việc tạo nội dung tính giá riêng: dựng cảnh và video trending bằng giá trên web nhân 150%, làm tròn lên. Ưu đãi lần đầu (video đầu tiên, lượt trending đầu tiên) chỉ có khi dùng trang web; gọi bằng API không được giảm và cũng không làm mất ưu đãi đó.

Giá hiện hành luôn có trong GET /api/me, mục pricing.api. Báo giá trong GET /api/episodes/{id} (quote) đã theo giá API khi gọi bằng khoá. Mỗi lần trừ trả về charged; sổ linh thạch ghi thêm "(API)". Viết kịch bản không thành thì được hoàn ngay.

Sáu bước dưới đây đúng với các bước bạn bấm trên trang web. Bản chạy được trọn vẹn có trong file ví dụ Python ở đầu trang.

Bước 1. Hệ thống viết kịch bản từ ý tưởng (miễn phí)

curl -X POST https://lin-ai-video.hkdq.space/api/episodes/draft \
  -H "Authorization: Bearer $LIN_AI_KEY" -H "Content-Type: application/json" \
  -d '{"idea": "Thỏ và Rùa chạy thi lần hai, kết thúc bất ngờ.", "sceneCount": 5, "voiceGender": "female"}'

# Trả về: { "json": "<chuỗi JSON prompt>", "issues": [] }

JSON prompt có khuôn { title, style, characters: [{ key, name, description }], scenes: [{ prompt, voice }] }. Bạn sửa được trước khi tạo tập, hoặc tự viết cả JSON và bỏ qua bước này. Nhân vật có mặt trong cảnh nào thì prompt của cảnh đó phải nhắc đúng key của nhân vật.

Bước 2. Tạo tập (miễn phí)

curl -X POST https://lin-ai-video.hkdq.space/api/episodes \
  -H "Authorization: Bearer $LIN_AI_KEY" -H "Content-Type: application/json" \
  -d '{"json": "<chuỗi JSON prompt ở bước 1>", "aspect": "9:16", "voiceGender": "female", "captions": true}'

# Trả về: { "id": "<mã tập>" }

Bước 3. Ảnh nhân vật (miễn phí)

Đọc tập để lấy danh sách nhân vật, xin tạo ảnh cho từng nhân vật, chờ trạng thái thành pending_review rồi duyệt. Có ảnh riêng thì tải lên thay cho việc tạo, ảnh tải lên được duyệt luôn.

curl https://lin-ai-video.hkdq.space/api/episodes/$TAP -H "Authorization: Bearer $LIN_AI_KEY"
# episode.cast: [{ "id": "...", "key": "character_tho", "status": "no_image" }, ...]

curl -X POST https://lin-ai-video.hkdq.space/api/characters/episode/$NHAN_VAT/image   -H "Authorization: Bearer $LIN_AI_KEY"
curl -X POST https://lin-ai-video.hkdq.space/api/characters/episode/$NHAN_VAT/approve -H "Authorization: Bearer $LIN_AI_KEY"

# Hoặc dùng ảnh của bạn:
curl -X POST https://lin-ai-video.hkdq.space/api/characters/episode/$NHAN_VAT/upload \
  -H "Authorization: Bearer $LIN_AI_KEY" -F "image=@tho.jpg;type=image/jpeg"

Bước 4. Gửi dựng (trừ linh thạch)

curl -X POST https://lin-ai-video.hkdq.space/api/episodes/$TAP/render \
  -H "Authorization: Bearer $LIN_AI_KEY" -H "Content-Type: application/json" -d '{}'

# Trả về: { "charged": 50, "scenes": 5, "balance": 450 }

Số sẽ trừ có sẵn ở quote.total khi đọc tập. Làm lại vài cảnh thì gửi {"sceneIds": ["<mã cảnh>"]}.

Bước 5. Chờ dựng và ghép

Đọc lại tập cho tới khi episode.status là done. Ở chế độ ghép tự động, cảnh cuối xong là hệ thống tự ghép.

Bước 6. Tải video

curl -L -o episode.mp4 https://lin-ai-video.hkdq.space/api/episodes/$TAP/download -H "Authorization: Bearer $LIN_AI_KEY"

Video được giữ có hạn (xem keepDays ở /api/me). Hết hạn thì video bị xoá, kịch bản và nhân vật vẫn còn.

Gửi một ảnh nhân vật kèm một video nguồn (file, hoặc link TikTok). Hệ thống thay nhân vật chính của video bằng nhân vật trong ảnh và giữ tiếng gốc.

curl -X POST https://lin-ai-video.hkdq.space/api/trends \
  -H "Authorization: Bearer $LIN_AI_KEY" \
  -F "character=@character.jpg;type=image/jpeg" \
  -F "video=@source.mp4;type=video/mp4"
# hoặc thay dòng video bằng:  -F "url=https://www.tiktok.com/@.../video/..."

# Trả về: { "id": "<mã video>", "cost": 30 }

curl https://lin-ai-video.hkdq.space/api/trends -H "Authorization: Bearer $LIN_AI_KEY"
# trends: [{ "id": "...", "status": "queued | processing | done | failed | expired", "error": null }], terms: { "cost": 30, "maxSeconds": 30 }

curl -L -o result.mp4 "https://lin-ai-video.hkdq.space/api/trends/$VIDEO/video?download=1" -H "Authorization: Bearer $LIN_AI_KEY"

Phải ghi rõ kiểu file trong form (type=image/jpeg, type=video/mp4); máy chủ kiểm tra theo đó. Giá và số giây được dùng nằm ở terms.

Giới hạn tần suất, chỉ tính khi gọi bằng khoá API, đếm theo từng phút cho mỗi tài khoản (mọi khoá của một tài khoản dùng chung):

• Đọc (GET): 120 lần mỗi phút.
• Ghi (POST, PATCH, DELETE): 20 lần mỗi phút.
• Gửi khoá sai 20 lần trong một phút từ cùng một địa chỉ IP thì mọi khoá từ IP đó bị chặn tới hết phút.
• Vượt mức: HTTP 429, { "code": "RATE_LIMITED", "retryAfter": 37 }, kèm header Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining.

Giới hạn nội dung đang áp dụng (giống khi dùng trang web; số mới nhất luôn có trong GET /api/me, mục limits):

Mọi lỗi trả về JSON { "error": "câu báo tiếng Việt", "code": "MÃ" }. Dựa vào code khi có để xử lý trong script; câu trong error có thể đổi chữ.

Mã HTTP

Giá trị của code