跳到主要内容

本地 API 概览

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。请求当前构建不支持的平台会返回 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"],
        "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发布内容✅ 已支持
follow关注用户✅ 已支持
unfollow取消关注✅ 已支持
account_warmup账号预热✅ 已支持
comment为帖子发表新评论✅ 已支持
boost_comment点赞/回复已有评论✅ 已支持
login登录账号✅ 已支持
profile更新个人资料✅ 已支持
match_account匹配设备上的账号✅ 已支持
like点赞帖子✅ 已支持
view观看帖子一段时间✅ 已支持
favorite将帖子保存到收藏夹✅ 已支持
repost转发 TikTok 视频✅ 支持 — 仅 TikTok
message发送私信❌ 不可用 §
follow_suggested关注建议账号✅ 支持 — 仅 TikTok
super_marketing超级营销活动✅ 已支持 †
scrape_user抓取用户数据🔜 即将推出
† 超级营销使用专用端点

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

§ message 没有实现

message 过去会被创建任务接受，但脚本二进制在两个平台上都没有对应的处理分支，因此这类任务最终都会在设备上以 "Unknown script" 失败。现在它会在创建阶段就被拒绝，并说明原因。如需群发私信，请使用 super_marketing，它通过目标数据集来驱动私信。

平台限定的脚本

repost 和 follow_suggested 仅实现了 TikTok。针对 Instagram 创建这类任务会被直接拒绝，而不是排入队列——此前这类任务会被创建，然后在设备上失败。

script_config 校验​

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

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

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

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

任务状态​

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

后续​