본문으로 건너뛰기

任务管理 API

本页面记录了管理 TikMatrix 任务的所有可用 API 端点。

创建任务​

为一个或多个设备或用户名创建新任务。

  • 端点： POST /api/v1/task
  • Content-Type： application/json

请求参数​

API 支持两种模式创建任务：

模式 1：设备模式 - 使用 serials 为设备创建任务 模式 2：用户名模式 - 使用 usernames 直接为特定账号创建任务

参数类型必需描述
serialsstring[]条件必需设备序列号数组（如果未提供 usernames 则必需）
usernamesstring[]条件必需用户名数组（如果未提供 serials 则必需）。提供此参数时，直接为这些账号创建任务。
script_namestring是要执行的脚本名称
script_configobject是脚本的配置参数（请参阅对应脚本文档）
enable_multi_accountboolean否是否启用多账号模式（默认：false）。仅在设备模式下生效。
start_timestring否计划执行时间，格式为 "HH:MM"
close_appboolean否작업이 끝난 후 대상 앱을 닫을지(강제 종료할지) 여부(기본값: true). false로 설정하면 작업 완료 후에도 앱이 계속 실행됩니다.
platformstring否대상 플랫폼(tiktok 또는 instagram). TikMatrix Pro에서만 사용되며 단일 플랫폼 빌드에서는 무시됩니다.

支持的脚本​

脚本名称描述文档
postTikTok/Instagram에 동영상 또는 이미지 게시Post 스크립트 설정
follow사용자 팔로우 또는 언팔로우Follow 스크립트 설정
unfollow사용자 언팔로우Unfollow 스크립트 설정
account_warmup계정 워밍업Account Warmup 스크립트 설정
comment게시물에 댓글Comment 스크립트 설정
login계정 로그인로그인 스크립트 설정
profile프로필 업데이트프로필 스크립트 설정
match_account기기의 계정 매칭계정 매칭 스크립트 설정
like게시물에 좋아요좋아요 스크립트 설정
view게시물을 지정된 시간 동안 보기보기 스크립트 설정
favorite게시물을 즐겨찾기에 저장즐겨찾기 스크립트 설정
repostTikTok 동영상 다시 공유다시 공유 스크립트 설정
message직접 메시지 보내기메시지 스크립트 설정
follow_suggested추천 계정 팔로우추천 팔로우 스크립트 설정

示例​

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": "看看我的新视频！#热门 #推荐",
      "material_list": ["C:/Videos/video1.mp4"],
      "upload_wait_time": 60
    }
  }'

작업 후 앱을 열어 두기​

기본적으로 작업이 끝나면 대상 앱을 강제 종료하여 앱 내 동작과 일치시키고 기기 리소스를 확보합니다. "close_app": false를 전달하면 작업 완료 후에도 앱이 계속 실행됩니다. 여러 작업을 연결하거나 기기에서 결과를 확인할 때 유용합니다:

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
  }'

有关 script_config 的详细参数和更多示例，请参阅 Post 脚本配置。

响应​

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

列表任务​

使用可选过滤条件查询任务。

  • 端点： GET /api/v1/task
参数类型必需描述
statusinteger否按状态过滤（0=pending, 1=running, 2=completed, 3=failed）
serialstring否按设备序列号过滤
script_namestring否按脚本名称过滤
sourcestring否按来源过滤（"ui" 或 "api"）
pageinteger否页码（默认：1）
page_sizeinteger否每页条目数（默认：20，最大：100）

获取任务详情​

获取指定任务的详细信息。

  • 端点： GET /api/v1/task/{task_id}

删除任务​

删除任务。如果任务正在运行，会先尝试停止它。

  • 端点： DELETE /api/v1/task/{task_id}

批量删除任务​

一次删除多个任务，正在运行的任务会先被停止。

  • 端点： DELETE /api/v1/task/batch
  • 请求体： { "task_ids": [1, 2, 3] }

停止任务​

停止正在运行的任务。

  • 端点： POST /api/v1/task/{task_id}/stop

重试失败任务​

重试单个失败任务。

  • 端点： POST /api/v1/task/{task_id}/retry

重试所有失败任务​

一次性重试所有失败的任务。

  • 端点： POST /api/v1/task/retry-all

获取任务统计​

获取任务总体统计数据。

  • 端点： GET /api/v1/task/stats
  • 响应： 返回 total、pending、running、completed、failed 的计数。

检查 API 许可​

检查你的许可证是否支持 API 访问。

  • 端点： GET /api/v1/license/check
  • 注意： Starter 计划会返回错误码 40301；Pro/Team/Business 计划可访问 API。