API quản lý task

Trang này tổng hợp toàn bộ endpoint dùng để quản lý task trong TikMatrix.

Tạo task

Tạo task mới cho một hoặc nhiều thiết bị/tài khoản.

• Endpoint: POST /api/v1/task
• Content-Type: application/json

Tham số request

API hỗ trợ 2 chế độ tạo task:

Chế độ 1: Thiết bị - dùng serials để tạo task theo thiết bị Chế độ 2: Username - dùng usernames để tạo task trực tiếp cho tài khoản chỉ định

Tham số	Kiểu	Bắt buộc	Mô tả
serials	string[]	Bắt buộc có điều kiện	Mảng serial thiết bị (bắt buộc nếu không có usernames)
usernames	string[]	Bắt buộc có điều kiện	Mảng username (bắt buộc nếu không có serials). Nếu truyền tham số này, task được tạo trực tiếp cho các tài khoản đó
script_name	string	Có	Tên script cần chạy
script_config	object	Có	Tham số cấu hình script (xem tài liệu từng script)
enable_multi_account	boolean	Không	Bật chế độ multi-account hay không (mặc định false), chỉ có hiệu lực ở chế độ thiết bị
start_time	string	Không	Thời gian chạy theo lịch, định dạng HH:MM
close_app	boolean	Không	Có đóng (buộc dừng) ứng dụng mục tiêu sau khi tác vụ kết thúc hay không (mặc định: true). Đặt false để giữ ứng dụng chạy sau khi hoàn tất.
platform	string	Không	Nền tảng mục tiêu (tiktok hoặc instagram). Chỉ TikMatrix Pro sử dụng; bị bỏ qua ở các bản dựng một nền tảng.

Script được hỗ trợ

Tên script	Mô tả	Tài liệu
post	Đăng video/hình ảnh lên TikTok/Instagram	Cấu hình script Post
follow	Theo dõi người dùng	Cấu hình script Follow
unfollow	Bỏ theo dõi người dùng	Cấu hình script Unfollow
account_warmup	Làm ấm tài khoản	Cấu hình script Account Warmup
comment	Bình luận bài viết	Cấu hình script Comment
login	Đăng nhập tài khoản	Cấu hình script Login
profile	Cập nhật hồ sơ	Cấu hình script Profile
match_account	Ghép tài khoản trên thiết bị	Cấu hình script Match Account
like	Thả tim bài đăng	Cấu hình script Like
view	Xem bài đăng trong một khoảng thời gian	Cấu hình script View
favorite	Lưu bài đăng vào Yêu thích	Cấu hình script Favorite
repost	Đăng lại video TikTok	Cấu hình script Repost
message	Gửi tin nhắn	Cấu hình script Message
follow_suggested	Theo dõi tài khoản gợi ý	Cấu hình script Follow Suggested

Ví dụ

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "script_config": {
      "content_type": 0,
      "captions": "Video mới đây! #trend #de_xuat",
      "material_list": ["C:/Videos/video1.mp4"],
      "upload_wait_time": 60
    }
  }'

Giữ ứng dụng mở sau tác vụ

Theo mặc định, ứng dụng mục tiêu bị buộc dừng khi tác vụ kết thúc, để khớp với hành vi trong phần mềm và giải phóng tài nguyên thiết bị. Truyền "close_app": false để giữ ứng dụng chạy sau khi hoàn tất — hữu ích khi nối tiếp nhiều tác vụ hoặc kiểm tra kết quả trên thiết bị:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "like",
    "script_config": {
      "target_post_url": "https://www.tiktok.com/@user/video/123"
    },
    "close_app": false
  }'

Để xem chi tiết script_config và thêm ví dụ, xem Cấu hình script Post.

Phản hồi

{
  "code": 0,
  "message": "success",
  "data": {
    "task_ids": [101, 102],
    "created_count": 2
  }
}

Liệt kê task

Truy vấn task với bộ lọc tùy chọn.

• Endpoint: GET /api/v1/task

Tham số	Kiểu	Bắt buộc	Mô tả
status	integer	Không	Lọc theo trạng thái (0=pending, 1=running, 2=completed, 3=failed)
serial	string	Không	Lọc theo serial thiết bị
script_name	string	Không	Lọc theo tên script
source	string	Không	Lọc theo nguồn (ui hoặc api)
page	integer	Không	Số trang (mặc định: 1)
page_size	integer	Không	Số bản ghi/trang (mặc định: 20, tối đa: 100)

Lấy chi tiết task

Lấy chi tiết theo task_id.

• Endpoint: GET /api/v1/task/{task_id}

Xóa task

Xóa một task. Nếu task đang chạy, hệ thống sẽ cố dừng trước.

• Endpoint: DELETE /api/v1/task/{task_id}

Xóa hàng loạt task

Xóa nhiều task cùng lúc, task đang chạy sẽ được dừng trước.

• Endpoint: DELETE /api/v1/task/batch
• Request Body: { "task_ids": [1, 2, 3] }

Dừng task

Dừng task đang chạy.

• Endpoint: POST /api/v1/task/{task_id}/stop

Retry task thất bại

Retry một task thất bại.

• Endpoint: POST /api/v1/task/{task_id}/retry

Retry toàn bộ task thất bại

Retry tất cả task thất bại cùng lúc.

• Endpoint: POST /api/v1/task/retry-all

Thống kê task

Lấy số liệu tổng hợp task.

• Endpoint: GET /api/v1/task/stats
• Response: trả về số lượng total, pending, running, completed, failed

Kiểm tra quyền API

Kiểm tra giấy phép có hỗ trợ API hay không.

• Endpoint: GET /api/v1/license/check
• Lưu ý: gói Starter sẽ trả lỗi 40301; gói Pro/Team/Business có quyền dùng API