跳到主要内容

本地 API 概览

脚本能力更新\nPro 的 Threads 支持 message、follow_back、scrape_users 和 repost；post 的 content_type = 2 表示纯文本。TikTok/Instagram 的 standalone message 不可用，请使用 Super Marketing。\n:::

TikMatrix 提供了一个本地的 RESTful API，允许你以编程方式管理任务。这对于将 TikMatrix 集成到你自己的自动化系统、构建自定义工作流程或创建批量操作非常有用。

要求​

许可证要求

本地 API 仅对 Pro、Team 和 Business 计划用户开放。 Starter 计划不提供 API 访问权限。

基础 URL​

API 在本机运行，地址为：

http://localhost:50809/api/v1/
备注

端口 50809 为默认端口。请在发起请求前确保 TikMatrix 已在运行。

响应格式​

所有 API 响应遵循以下格式：

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

响应码说明​

Code描述
0成功
40001参数错误 - 无效的请求参数，包括未通过校验的 script_config
40002参数错误 - 缺少 script_name
40003参数错误 - 该构建或该平台不支持此脚本、脚本没有实现，或任务状态无效
40004参数错误 - 仅正在运行的任务可以停止
40005参数错误 - task_ids 不能为空
40301禁止 - API 访问需要 Pro+ 计划
40401未找到 - 资源不存在
50001服务器内部错误

快速开始​

1. 检查 API 访问权限​

首先，确认你的许可证是否支持 API：

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

示例响应：

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

2. 查询脚本及其参数​

GET /api/v1/schema 会列出当前构建能运行的每一个脚本，以及各自 script_config 的确切字段——名称、类型、默认值、可选值，以及哪些是必填。它由服务端校验所用的同一份目录生成，因此不会与创建任务时的实际接受范围产生偏差。

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

两个可选查询参数：

参数作用
platform把结果限定为 tiktok、instagram 或 threads。请求当前构建不支持的平台会返回 40001。默认返回该构建支持的全部平台。
include_unavailable设为 true 时，同时列出 API 接受但没有可用实现的脚本名，每一项都带 unavailable_reason。

响应（节选）：

{
  "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 说明一次请求会产生多少任务：per_device 为每台设备创建一个任务（多账号模式下为每个账号一个），per_item 则按指定字段的每一项、每台设备各创建一个。

3. 创建任务​

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": "看看我的新视频！#热门"
    },
    "enable_multi_account": false
  }'

4. 查询任务列表​

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

可用脚本​

script_name 参数可接受下列值：

脚本名描述API 支持
post发布视频、图片或 Threads 纯文本帖子✅ 已支持
follow关注用户✅ 已支持
unfollow取消关注用户✅ 已支持
account_warmup账号预热✅ 已支持
comment在帖子下发表新评论✅ 已支持
boost_comment点赞 / 回复已有评论✅ 已支持
login登录账号✅ 已支持
profile更新个人资料✅ 已支持
match_account匹配设备上的账号✅ 已支持
like点赞帖子✅ 已支持
view观看帖子一段时间✅ 已支持
favorite将帖子保存到收藏✅ 已支持
repost转发 TikTok 视频或 Threads 帖子✅ 支持 — TikTok 和 Threads
message发送私信✅ 支持 — 仅 Threads
follow_back关注粉丝列表中的账号✅ 支持 — TikTok、Instagram 和 Threads
follow_suggested关注推荐账号✅ 支持 — 仅 TikTok
custom_script运行你自行注册的程序✅ 已支持 ‡
super_marketing超级营销活动✅ 已支持 †
scrape_users导出粉丝、关注或搜索得到的用户名✅ 支持 — TikTok、Instagram 和 Threads
auto_reply回复私信和评论❌ 不能通过 API 创建 §
† 超级营销使用专用端点

超级营销活动不通过 POST /api/v1/task 创建。它基于可复用的目标数据集运行，并拥有独立的专用端点——详见超级营销脚本配置。

仅限 Threads 的私信

独立的 message 任务会执行 Threads 的「个人主页 → 消息」流程。 对于 TikTok 和 Instagram，请改用带目标数据集的 super_marketing。

平台限定的脚本

repost 已在 TikTok 和 Threads 上实现；follow_suggested 仍仅支持 TikTok。 follow_back 和 scrape_users 使用各平台真机上的粉丝/搜索界面， 适用于 TikTok、Instagram 和 Threads。

‡ 自定义脚本需先注册

custom_script 运行你在设备 → 自定义脚本中注册的程序。将其 id 传入 script_config.custom_script_id——详见自定义脚本。

§ 自动回复从其专属页面运行

auto_reply 在 Pro 及以上套餐中，可在 TikTok、Instagram 和 Threads 上回复私信和评论。其回复轮次由应用中的自动回复页面安排，该页面保存回复规则、工作时间和暂停开关，因此无法通过 POST /api/v1/task 创建。

script_config 校验​

创建任务前会先用上面的 schema 校验 script_config，因此参数写错会立刻返回 400 并指出是哪个字段，而不是稍后在手机上失败。三种情况会被拒绝：

  • 必填字段缺失或为空；
  • 二选一字段组一个都没填（例如 follow 需要 target_users / target_user 其中之一）；
  • 取值超出该字段 choices 所列范围。

schema 中未列出的键会被忽略而非拒绝——桌面端自己也会通过同一个对象传递额外的键，拒绝未知键会破坏现有集成。这些键会记入服务端日志，方便你发现拼写错误。

数字可以用字符串形式传递（"20" 与 20 均可），与脚本本身的接受范围一致。

任务状态​

状态码状态文本描述
0pending任务等待执行
1running任务正在执行
2completed任务执行成功
3failed任务执行失败

后续​