LarAPI Documentation

Chào mừng đến với LarAPI. API của chúng tôi cung cấp khả năng tích hợp các công cụ AI mạnh mẽ (Inpaint, Upscale, Vision...) vào ứng dụng của bạn một cách đơn giản thông qua giao thức RESTful chuẩn.

Base URL: https://larapi.dev/api/v1

# Xác thực (Authentication)

Mọi request đến API cần phải được xác thực bằng API Key. Bạn có thể lấy khóa này trong trang Dashboard > API Key.

Gửi API Key thông qua Header:

HTTP Header
apikey: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Quy trình xử lý (Async Flow)

Do các tác vụ AI (như Upscale 4K) tốn nhiều thời gian xử lý (từ 5s - 30s), chúng tôi sử dụng cơ chế Bất đồng bộ (Asynchronous).

  1. Gửi Request: Bạn gọi API /task/create.
  2. Nhận Task ID: Server trả về ngay lập tức một task_id (trạng thái: pending).
  3. Polling: Bạn dùng ID đó gọi /task/status/{id} mỗi 2-3 giây để kiểm tra.
  4. Hoàn tất: Khi trạng thái chuyển thành success, bạn sẽ nhận được URL ảnh kết quả.
POST

/task/create

Tạo một tác vụ xử lý ảnh mới. Credits sẽ bị trừ khi task hoàn thành.

Body Param Type Required Mô tả
module string Yes Tên module (VD: upscale-image, inpaint-image).
image_url string Yes URL công khai của ảnh cần xử lý (JPG/PNG).
mask_url string Optional URL ảnh mặt nạ (đen trắng) dùng cho Inpaint.
webhook_url string Optional URL nhận kết quả khi xong (thay vì Polling).
curl -X POST https://larapi.dev/api/v1/task/create \
-H "apikey: sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "module": "inpaint-image", "image_url": "https://example.com/photo.jpg", "mask_url": "https://example.com/mask.png" }'
const resp = await fetch('https://larapi.dev/api/v1/task/create', {
method: 'POST',
headers: {
'apikey': 'sk_live_YOUR_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
module: 'inpaint-image',
image_url: 'https://example.com/photo.jpg'
})
});
const data = await resp.json();
import requests

url = "https://larapi.dev/api/v1/task/create"
headers = {"apikey": "sk_live_YOUR_KEY"}
payload = {
"module": "inpaint-image",
"image_url": "https://example.com/photo.jpg"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response Example (200 OK):

{
  "status": "success",
  "task_id": "tsk_8291023910",
  "message": "Task created successfully",
  "check_url": "https://larapi.dev/api/v1/task/status/tsk_8291023910"
}
GET

/task/status/{task_id}

Kiểm tra trạng thái xử lý của tác vụ.

Đang xử lý

{
  "task_id": "tsk_8291023910",
  "status": "processing", // hoặc "pending"
  "progress": 50,
  "result": null
}

Hoàn thành

{
  "task_id": "tsk_8291023910",
  "status": "success",
  "result": "https://cdn.larapi.dev/output/xyz.png",
  "credits_deducted": 0.2
}

Danh sách Module ID

Sử dụng các ID này trong tham số module.

Module Name Mô tả Price
inpaint-image Xóa vật thể (cần mask_url). 0.2 cr
upscale-image Làm nét ảnh (2x, 4x). 0.5 cr
tiktok-downloader Tải video không logo. 0.1 cr
vision-ai Phân tích nội dung ảnh. 0.3 cr

# Mã lỗi & Xử lý sự cố

Khi API gặp sự cố, chúng tôi sẽ trả về HTTP Status tương ứng (4xx, 5xx) kèm theo JSON body chứa code cụ thể để bạn xử lý logic.

Cấu trúc lỗi mẫu
{
  "status": "error",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Your balance is too low to perform this task.",
  "hint": "Please top up at https://larapi.dev/buy-credits" // Optional
}
Error Code HTTP Mô tả & Cách khắc phục
UNAUTHORIZED 401 API Key bị thiếu hoặc không hợp lệ. Vui lòng kiểm tra lại Header apikey.
SESSION_EXPIRED 401 Phiên làm việc (Session Token) đã hết hạn. Vui lòng thực hiện đăng nhập lại hoặc refresh token.
INSUFFICIENT_CREDITS 402 Tài khoản không đủ Credits để thực hiện tác vụ này. Nạp thêm tại đây.
VALIDATION_ERROR 422 Dữ liệu gửi lên không đúng định dạng (Thiếu params bắt buộc, sai kiểu dữ liệu...). Kiểm tra lại trường errors trong response để biết chi tiết.
INVALID_URL 422 URL hình ảnh hoặc Webhook không truy cập được (404, 403) hoặc không phải định dạng ảnh hợp lệ.
MODULE_NOT_FOUND 404 Tên Module gửi lên không tồn tại trong hệ thống. Xem danh sách Module khả dụng ở trên.
TASK_NOT_FOUND 404 Không tìm thấy Task ID này. Có thể Task đã quá hạn lưu trữ (24h) hoặc ID bị sai.
RATE_LIMIT 429 Bạn gửi quá nhiều request trong thời gian ngắn. Vui lòng chậm lại (Mặc định: 60 req/phút).
CONCURRENCY_LIMIT 429 Bạn đang chạy quá nhiều tác vụ xử lý song song. Hãy đợi các tác vụ cũ hoàn thành trước khi tạo mới.
ALREADY_REFUNDED 409 Task này đã được hoàn tiền trước đó, không thể thực hiện lại thao tác.