작업 관리 API
스크립트 목록 업데이트\nTask API에 follow_back과 scrape_users가 추가되었습니다. repost는 TikTok/Threads, message는 Threads에서만 지원합니다. 자세한 내용은 현지화된 설정 페이지를 참조하세요.\n:::
이 페이지는 TikMatrix 작업을 관리하기 위한 모든 사용 가능한 API 엔드포인트를 기록합니다.
작업 생성
하나 이상의 기기 또는 사용자명에 대해 새 작업을 생성합니다.
- 엔드포인트:
POST /api/v1/task - Content-Type:
application/json
요청 매개변수
API는 작업을 생성하는 두 가지 모드를 지원합니다:
모드 1: 기기 모드 - serials을 사용하여 기기에 대한 작업을 생성합니다
모드 2: 사용자명 모드 - usernames을 사용하여 특정 계정에 대한 작업을 직접 생성합니다
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
| serials | string[] | 조건부 필수 | 기기 일련번호 배열(usernames을 제공하지 않은 경우 필수) |
| usernames | string[] | 조건부 필수 | 사용자명 배열(serials을 제공하지 않은 경우 필수). 이 매개변수를 제공할 때 이러한 계정에 대해 작업을 직접 생성합니다. |
| script_name | string | 예 | 실행할 스크립트의 이름 |
| script_config | object | 예 | 스크립트의 설정 매개변수(해당 스크립트 문서 참조) |
| enable_multi_account | boolean | 아니요 | 다중 계정 모드를 활성화할지 여부(기본값: false). 기기 모드에서만 효과가 있습니다. |
| start_time | string | 아니요 | 예약된 실행 시간, 형식 "HH:MM" |
| close_app | boolean | 아니요 | 작업이 끝난 후 대상 앱을 닫을지(강제 종료할지) 여부(기본값: true). false로 설정하면 작업 완료 후에도 앱이 계속 실행됩니다. |
| platform | string | 아니요 | 대상 플랫폼(tiktok, instagram 또는 threads). TikMatrix Pro에서만 사용되며 단일 플랫폼 빌드에서는 무시됩니다. |
지원되는 스크립트
| 스크립트 이름 | 설명 | 문서 |
|---|---|---|
| post | TikTok/Instagram에 동영상 또는 이미지 게시 | Post 스크립트 설정 |
| follow | 사용자 팔로우 또는 언팔로우 | Follow 스크립트 설정 |
| unfollow | 사용자 언팔로우 | Unfollow 스크립트 설정 |
| account_warmup | 계정 워밍업 | Account Warmup 스크립트 설정 |
| comment | 게시물에 댓글 | Comment 스크립트 설정 |
| login | 계정 로그인 | 로그인 스크립트 설정 |
| profile | 프로필 업데이트 | 프로필 스크립트 설정 |
| match_account | 기기의 계정 매칭 | 계정 매칭 스크립트 설정 |
| like | 게시물에 좋아요 | 좋아요 스크립트 설정 |
| view | 게시물을 지정된 시간 동안 보기 | 보기 스크립트 설정 |
| favorite | 게시물을 즐겨찾기에 저장 | 즐겨찾기 스크립트 설정 |
| repost | TikTok 동영상 다시 공유 | 다시 공유 스크립트 설정 |
| 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
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
| status | integer | 아니요 | 상태로 필터링(0=pending, 1=running, 2=completed, 3=failed) |
| serial | string | 아니요 | 기기 일련번호로 필터링 |
| script_name | string | 아니요 | 스크립트 이름으로 필터링 |
| source | string | 아니요 | 소스로 필터링("ui" 또는 "api") |
| page | integer | 아니요 | 페이지 번호(기본값: 1) |
| page_size | integer | 아니요 | 페이지당 항목 수(기본값: 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에 액세스할 수 있습니다.