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

Tổng quan Local API

Cập nhật script\nThreads trong Pro hỗ trợ message, follow_back, scrape_users và repost; content_type = 2 của post là bài chỉ có văn bản. Message độc lập không có trên TikTok/Instagram, hãy dùng Super Marketing.\n:::

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, instagram hoặc threads. 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", "threads"],
        "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 video, hình ảnh hoặc bài viết chỉ có chữ trên Threads✅ Đượ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ợ
commentĐăng bình luận mới vào bài viết✅ Đượ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 các tài khoản trên thiết bị✅ Được hỗ trợ
likeThả tim bài viết✅ Được hỗ trợ
viewXem bài viết trong một khoảng thời gian✅ Được hỗ trợ
favoriteLưu bài viết vào Yêu thích✅ Được hỗ trợ
repostĐăng lại video TikTok hoặc bài viết Threads✅ Được hỗ trợ — TikTok và Threads
messageGửi tin nhắn trực tiếp✅ Được hỗ trợ — chỉ Threads
follow_backTheo dõi các tài khoản từ danh sách người theo dõi✅ Được hỗ trợ — TikTok, Instagram và Threads
follow_suggestedTheo dõi các tài khoản được gợi ý✅ Được hỗ trợ — chỉ TikTok
custom_scriptChạy một chương trình do bạn tự đăng ký✅ Được hỗ trợ ‡
super_marketingChiến dịch super marketing✅ Được hỗ trợ †
scrape_usersXuất tên người dùng đang theo dõi, người theo dõi hoặc từ kết quả tìm kiếm✅ Được hỗ trợ — TikTok, Instagram và Threads
auto_replyTrả lời tin nhắn trực tiếp và bình luận❌ Không qua API §
† Super marketing dùng endpoint riêng

Chiến dịch super marketing không được tạo qua POST /api/v1/task. Chiến dịch 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.

Nhắn tin trực tiếp chỉ dành cho Threads

Tác vụ message độc lập thực hiện luồng Threads profile → Tin nhắn. Với TikTok và Instagram, hãy dùng super_marketing cùng tập dữ liệu mục tiêu.

Script riêng theo nền tảng

repost chỉ được triển khai cho TikTok và Threads; follow_suggested vẫn chỉ dành cho TikTok. follow_back và scrape_users sử dụng giao diện người theo dõi/tìm kiếm thật trên thiết bị của từng nền tảng và khả dụng trên TikTok, Instagram và Threads.

‡ Phải đăng ký script tùy chỉnh trước

custom_script chạy chương trình bạn đã đăng ký trong Thiết bị → Script tùy chỉnh. Truyền id của chương trình vào script_config.custom_script_id — xem Script tùy chỉnh.

§ Tự động trả lời chạy từ trang riêng

auto_reply trả lời tin nhắn trực tiếp và bình luận trên TikTok, Instagram và Threads, với gói Pro trở lên. Các đợt trả lời được lên lịch bởi trang Tự động trả lời trong ứng dụng, nơi giữ các quy tắc trả lời, giờ làm việc và công tắc tạm dừng, nên không thể tạo qua POST /api/v1/task.

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​