본문으로 건너뛰기

로컬 API 개요

TikMatrix는 프로그래밍 방식으로 작업을 관리할 수 있는 로컬 RESTful API를 제공합니다. 이는 TikMatrix를 자체 자동화 시스템과 통합하거나, 사용자 정의 워크플로우를 구축하거나, 일괄 작업을 생성하는 데 유용합니다.

요구 사항​

라이선스 요구 사항

로컬 API는 Pro, Team, Business 플랜 구독자만 사용할 수 있습니다. Starter 플랜은 API에 액세스할 수 없습니다.

기본 URL​

API는 로컬 머신에서 실행됩니다:

http://localhost:50809/api/v1/
노트

포트 50809는 기본 포트입니다. API 요청을 하기 전에 TikMatrix가 실행 중인지 확인하세요.

응답 형식​

모든 API 응답은 다음 형식을 따릅니다:

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

응답 코드​

코드설명
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_unavailabletrue로 지정하면 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,
    "start_time": "14:30"
  }'

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게시물을 즐겨찾기에 저장✅ 지원됨
repostTikTok 동영상 리포스트✅ 지원 — TikTok 전용
message다이렉트 메시지❌ 사용 불가 §
follow_suggested추천 계정 팔로우✅ 지원 — TikTok 전용
super_marketing슈퍼 마케팅 캠페인✅ 지원됨 †
scrape_user사용자 데이터 스크래핑🔜 출시 예정
† 슈퍼 마케팅은 전용 엔드포인트 사용

슈퍼 마케팅 캠페인은 POST /api/v1/task를 통해 생성하지 않습니다. 재사용 가능한 타겟 데이터셋을 기반으로 실행되며 전용 엔드포인트가 있습니다 — 슈퍼 마케팅 스크립트 구성을 참고하세요.

§ message에는 구현이 없습니다

message는 작업 생성 단계에서 받아들여졌지만, 스크립트 바이너리에 두 플랫폼 모두 처리 분기가 없어 이런 작업은 기기에서 "Unknown script"로 실패했습니다. 이제는 생성 시점에 그 이유와 함께 거부됩니다. 지금 다이렉트 메시지를 보내려면 대상 데이터셋을 통해 DM을 처리하는 super_marketing을 사용하세요.

플랫폼 전용 스크립트

repost와 follow_suggested는 TikTok용으로만 구현되어 있습니다. Instagram 대상으로 생성하면 대기열에 들어가지 않고 거부됩니다. 이전에는 작업이 생성된 뒤 기기에서 실패했습니다.

script_config 검증​

작업 생성은 아무것도 기록하기 전에 위 스키마로 script_config를 검증합니다. 따라서 잘못된 매개변수는 나중에 휴대폰에서 실패하는 작업이 아니라, 필드 이름을 알려주는 400으로 돌아옵니다. 거부되는 경우는 세 가지입니다:

  • 필수 필드가 없거나 비어 있음
  • 택일 그룹에서 어느 것도 설정되지 않음(예: follow는 target_users / target_user 중 하나가 필요)
  • 필드에 문서화된 choices 범위를 벗어난 값

스키마에 없는 키는 거부가 아니라 무시됩니다. 데스크톱 앱도 같은 객체로 자체 키를 전달하며, 모르는 키를 거부하면 기존 연동이 깨지기 때문입니다. 서버 로그에는 남으므로 앱 로그에서 오타를 찾을 수 있습니다.

숫자는 문자열로 보내도 됩니다(20뿐 아니라 "20"도 가능). 스크립트가 이미 받아들이는 형식과 같습니다.

작업 상태​

상태 코드상태 텍스트설명
0pending작업 실행 대기 중
1running작업 실행 중
2completed작업 성공적으로 완료
3failed작업 실패

다음 단계​