Chuyển tới nội dung chính

Tổng quan Local API

TikMatrix cung cấp một Local RESTful API, cho phép bạn quản lý task bằng lập trình. Điều này rất hữu ích khi tích hợp TikMatrix vào hệ thống tự động hóa riêng, xây dựng workflow tùy chỉnh, hoặc xử lý hàng loạt.

Yêu cầu​

Yêu cầu giấy phép

Local API chỉ mở cho người dùng gói Pro, Team và Business. Gói Starter không có quyền truy cập API.

Base URL​

API chạy trên máy cục bộ tại:

http://localhost:50809/api/v1/
ghi chú

Cổng mặc định là 50809. Hãy đảm bảo TikMatrix đang chạy trước khi gọi API.

Định dạng phản hồi​

Tất cả phản hồi API dùng cùng cấu trúc:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Mã phản hồi​

CodeMô tả
0Thành công
40001Yêu cầu không hợp lệ - Tham số không hợp lệ, bao gồm script_config không qua được kiểm tra
40002Lỗi tham số - thiếu script_name
40003Yêu cầu không hợp lệ - Script không được hỗ trợ trên bản dựng hoặc nền tảng này, không có phần triển khai, hoặc trạng thái task không hợp lệ
40004Lỗi tham số - chỉ có thể dừng các task đang chạy
40005Lỗi tham số - task_ids không thể trống
40301Forbidden - cần gói Pro+ để dùng API
40401Not found - tài nguyên không tồn tại
50001Lỗi nội bộ máy chủ

Bắt đầu nhanh​

1) Kiểm tra quyền truy cập API​

curl http://localhost:50809/api/v1/license/check

Ví dụ phản hồi:

{
  "code": 0,
  "message": "success",
  "data": {
    "plan_name": "Pro",
    "api_enabled": true,
    "device_limit": 20,
    "message": "API access enabled"
  }
}

2) Tra cứu các script và tham số của chúng​

GET /api/v1/schema mô tả mọi script mà bản dựng này chạy được cùng đúng các trường script_config mà nó nhận: tên, kiểu, giá trị mặc định, giá trị cho phép và trường nào bắt buộc. Nó được sinh ra từ chính danh mục mà máy chủ dùng để kiểm tra, nên không thể lệch khỏi những gì việc tạo task chấp nhận.

curl http://localhost:50809/api/v1/schema

Hai tham số truy vấn tuỳ chọn:

Tham sốTác dụng
platformGiới hạn danh sách theo tiktok hoặc instagram. Nền tảng không có trong bản dựng sẽ bị từ chối với mã 40001. Mặc định là mọi nền tảng của bản dựng.
include_unavailableĐặt true để liệt kê thêm những tên script mà API chấp nhận nhưng không có phần triển khai hoạt động. Mỗi mục đều kèm unavailable_reason.

Phản hồi (rút gọn):

{
  "code": 0,
  "message": "success",
  "data": {
    "build": { "platforms": ["tiktok"] },
    "scripts": [
      {
        "name": "follow",
        "internal_name": "follow",
        "summary": "Follow the given users. One task per target.",
        "platforms": ["tiktok", "instagram"],
        "available": true,
        "fan_out": { "kind": "per_item", "key": "target_users", "alt_key": "target_user" },
        "any_of": [["target_users", "target_user"]],
        "fields": [
          {
            "key": "access_method",
            "type": "string",
            "required": false,
            "default": "direct",
            "choices": ["direct", "search"],
            "description": "How to reach the profile: direct (via URL) or search."
          }
        ]
      }
    ]
  }
}

fan_out cho biết một yêu cầu sẽ sinh ra bao nhiêu task: per_device tạo một task cho mỗi thiết bị (hoặc mỗi tài khoản ở chế độ nhiều tài khoản), per_item tạo một task cho mỗi mục của trường được nêu, trên mỗi thiết bị.

3) Tạo task​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "script_name": "post",
    "script_config": {
      "content_type": 1,
      "captions": "Xem video mới của mình nhé! #trend"
    },
    "enable_multi_account": false
  }'

4) Liệt kê task​

curl "http://localhost:50809/api/v1/task?status=0&page=1&page_size=20"

Các script khả dụng​

script_name chấp nhận các giá trị sau:

Tên scriptMô tảHỗ trợ API
postĐăng nội dung✅ Được hỗ trợ
followTheo dõi người dùng✅ Được hỗ trợ
unfollowBỏ theo dõi người dùng✅ Được hỗ trợ
account_warmupLàm ấm tài khoản✅ Được hỗ trợ
commentBình luận✅ Được hỗ trợ
boost_commentThích / trả lời các bình luận hiện có✅ Được hỗ trợ
loginĐăng nhập tài khoản✅ Được hỗ trợ
profileCập nhật hồ sơ✅ Được hỗ trợ
match_accountGhép tài khoản trên thiết bị✅ Được hỗ trợ
likeThả tim✅ Được hỗ trợ
viewXem bài đăng trong một khoảng thời gian✅ Được hỗ trợ
favoriteLưu bài đăng vào Yêu thích✅ Được hỗ trợ
repostĐăng lại video TikTok✅ Được hỗ trợ — chỉ TikTok
messageGửi tin nhắn❌ Không khả dụng §
follow_suggestedTheo dõi tài khoản gợi ý✅ Được hỗ trợ — chỉ TikTok
super_marketingChiến dịch siêu marketing✅ Được hỗ trợ †
scrape_userThu thập dữ liệu người dùng🔜 Sắp ra mắt
† Super marketing dùng endpoint riêng

Chiến dịch super marketing không được tạo qua POST /api/v1/task. Nó chạy dựa trên tập dữ liệu mục tiêu có thể tái sử dụng và có các endpoint riêng — xem Cấu hình Script Super Marketing.

§ message không có phần triển khai

message từng được chấp nhận khi tạo task, nhưng tệp nhị phân script không có nhánh xử lý cho nó trên cả hai nền tảng, nên mọi task loại này đều thất bại trên máy với lỗi "Unknown script". Giờ nó bị từ chối ngay khi tạo, kèm lý do đó. Để gửi tin nhắn trực tiếp, hãy dùng super_marketing, vốn điều khiển DM qua một tập dữ liệu mục tiêu.

Script riêng theo nền tảng

repost và follow_suggested chỉ được triển khai cho TikTok. Tạo chúng cho mục tiêu Instagram sẽ bị từ chối thay vì đưa vào hàng đợi — trước đây task vẫn được tạo rồi thất bại trên máy.

Kiểm tra script_config​

Việc tạo task kiểm tra script_config theo schema ở trên trước khi ghi bất cứ thứ gì, nên tham số sai sẽ trả về 400 có nêu tên trường, thay vì thành một task thất bại trên điện thoại sau đó. Ba trường hợp bị từ chối:

  • trường bắt buộc bị thiếu hoặc để trống,
  • nhóm "một trong số" mà không thành viên nào được đặt (ví dụ follow cần một trong target_users / target_user),
  • giá trị nằm ngoài danh sách choices đã ghi của trường đó.

Những khoá không có trong schema sẽ bị bỏ qua chứ không bị từ chối — ứng dụng desktop cũng truyền khoá riêng qua chính đối tượng này, và từ chối khoá lạ sẽ làm hỏng các tích hợp hiện có. Chúng được ghi log ở phía máy chủ để bạn phát hiện lỗi gõ nhầm trong log ứng dụng.

Số có thể gửi dưới dạng chuỗi ("20" cũng như 20), khớp với những gì script vốn đã chấp nhận.

Trạng thái task​

Mã trạng tháiVăn bản trạng tháiMô tả
0pendingTask đang chờ chạy
1runningTask đang chạy
2completedTask chạy thành công
3failedTask chạy thất bại

Xem thêm​