슈퍼 마케팅 스크립트 구성
이 페이지에서는 슈퍼 마케팅 스크립트의 API 엔드포인트를 설명합니다. 다른 스크립트와 달리, 슈퍼 마케팅은 일반 POST /api/v1/task 엔드포인트를 통해 생성하지 않습니다 — 재사용 가능한 타겟 데이터셋을 기반으로 실행되며 전용 엔드포인트가 있습니다.
개요
슈퍼 마케팅 캠페인은 타겟 풀에 대해 여러 성장 액션(팔로우, 언팔로우, 신고, DM, 부스트, 대량 댓글)을 한 번에 결합하여 실행합니다. 타겟 풀은 데이터셋으로 저장됩니다:
- 데이터 유형 — 데이터셋에는
usernames(TikTok/Instagram/Threads 핸들) 또는post_links(게시물 URL)가 포함됩니다. - 전략 — 타겟을 기기에 배분하는 방식을 제어합니다:
shared_pool— 선택한 모든 기기/계정이 모든 타겟을 처리합니다.consume_once— 타겟을 기기 간에 분할하여 각 타겟을 한 번만 처리합니다.
일반적인 흐름:
- 타겟을 데이터셋에 가져오기 →
dataset_id획득. dataset_id를 참조하는 캠페인을 하나 이상의 기기에서 실행.
기능 토글(팔로우 / DM / 댓글 등)과 세부 설정은 데스크톱 앱의 저장된 구성(super_marketing_settings.json)에서 읽어옵니다. 실행 요청에 script_config를 전달하여 실행별로 오버라이드할 수 있습니다.
Threads는 프로필 탐색, 팔로우/언팔로우, DM (대상이 메시지 버튼을 노출하는 경우), 게시물 조회/좋아요/저장/리포스트, 댓글을 지원합니다. SMS 공유 기능은 Threads에 대응하는 워크플로우가 없어서 건너뜁니다. 계정 신고는 자동화 경로에서 지원하지 않는 수동 선택 신고 사유가 필요하기 때문에 의도적으로 건너뜁니다.
라이선스 요구 사항
모든 슈퍼 마케팅 엔드포인트는 로컬 API의 나머지 엔드포인트와 마찬가지로 Pro, Team, 또는 Business 플랜이 필요합니다.
데이터셋 가져오기
새 데이터셋을 만들거나 기존 데이터셋에 타겟을 추가합니다.
- 엔드포인트:
POST /api/v1/super-marketing/dataset
요청 본문
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| dataset_id | integer | No | — | 추가/교체할 기존 데이터셋 ID. 새로 만들려면 생략하거나 0 사용. |
| data_type | string | Yes | — | usernames 또는 post_links |
| strategy | string | Yes | — | shared_pool 또는 consume_once |
| entries | string[] | Yes* | [] | JSON 배열로 된 타겟. raw_text보다 우선 적용됩니다. |
| raw_text | string | Yes* | — | 줄바꿈으로 구분된 타겟 문자열(entries의 대안). |
| mode | string | No | append | append는 기존 항목에 추가; replace는 기존 항목을 먼저 지움. |
| label | string | No | — | 데이터셋의 선택적 레이블. |
노트
타겟은 entries 또는 raw_text 중 하나로 제공하세요. 중복 및 빈 항목은 무시됩니다. 단일 가져오기는 최대 100,000개 항목으로 제한됩니다.
예제
curl -X POST http://localhost:50809/api/v1/super-marketing/dataset \
-H "Content-Type: application/json" \
-d '{
"data_type": "usernames",
"strategy": "shared_pool",
"label": "캠페인 A 타겟",
"entries": ["@user_one", "@user_two", "@user_three"]
}'
줄바꿈으로 구분된 텍스트로 기존 데이터셋에 더 많은 타겟 추가:
curl -X POST http://localhost:50809/api/v1/super-marketing/dataset \
-H "Content-Type: application/json" \
-d '{
"dataset_id": 7,
"data_type": "usernames",
"strategy": "shared_pool",
"mode": "append",
"raw_text": "@user_four\n@user_five\n@user_six"
}'
응답 예제
{
"code": 0,
"message": "success",
"data": {
"dataset": {
"stats": {
"id": 7,
"data_type": "usernames",
"strategy": "shared_pool",
"label": "캠페인 A 타겟",
"total": 3,
"consumed": 0,
"remaining": 3,
"created_at": "2026-06-22 09:00:00",
"updated_at": "2026-06-22 09:00:00"
},
"entries": [
{ "id": 1, "value": "@user_one", "consumed": false, "consumed_by": null, "consumed_at": null, "created_at": "2026-06-22 09:00:00", "updated_at": "2026-06-22 09:00:00" }
]
},
"summary": {
"inserted": 3,
"duplicates": 0,
"skipped_empty": 0,
"removed": 0,
"truncated": 0
}
}
}
데이터셋 목록
소비 통계와 함께 모든 데이터셋을 조회합니다.
- 엔드포인트:
GET /api/v1/super-marketing/datasets
쿼리 매개변수
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| data_type | string | — | 선택적 필터: usernames 또는 post_links |
예제
curl "http://localhost:50809/api/v1/super-marketing/datasets?data_type=usernames"
응답 예제
{
"code": 0,
"message": "success",
"data": [
{
"id": 7,
"data_type": "usernames",
"strategy": "shared_pool",
"label": "캠페인 A 타겟",
"total": 6,
"consumed": 0,
"remaining": 6,
"created_at": "2026-06-22 09:00:00",
"updated_at": "2026-06-22 09:05:00"
}
]
}
데이터셋 가져오기
데이터셋의 통계와 항목 페이지를 가져옵니다.
- 엔드포인트:
GET /api/v1/super-marketing/dataset/{id}
쿼리 매개변수
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| limit | integer | 50 | 페이지당 항목 수(최대 500) |
| offset | integer | 0 | 건너뛸 항목 수 |
예제
curl "http://localhost:50809/api/v1/super-marketing/dataset/7?limit=100&offset=0"
데이터셋 초기화
데이터셋에서 모든 항목을 제거합니다. 데이터셋 레코드 자체는 유지되며(dataset_id는 향후 가져오기에서 유효하게 유지됩니다).
- 엔드포인트:
DELETE /api/v1/super-marketing/dataset/{id}
예제
curl -X DELETE http://localhost:50809/api/v1/super-marketing/dataset/7
응답 예제
{
"code": 0,
"message": "success",
"data": { "cleared": true, "dataset_id": 7 }
}
캠페인 실행
데이터셋의 타겟을 사용하여 지정된 기기에서 슈퍼 마케팅 캠페인을 시작합니다.
- 엔드포인트:
POST /api/v1/super-marketing/run
요청 본문
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| serials | string[] | Yes | [] | 실행할 기기 시리얼 번호 |
| dataset_id | integer | Yes | — | 캠페인 타겟을 제공하는 데이터셋 |
| enable_multi_account | boolean | No | false | 각 기기의 계정마다 작업 하나 생성 |
| merge_same_username_tasks | boolean | No | false | 기기의 모든 타겟을 타겟당 작업 대신 하나의 작업으로 묶기 |
| platform | string | No | — | 플랫폼 오버라이드(tiktok / instagram). 멀티 플랫폼 빌드에서만 유효 |
| min_interval | integer | No | 0 | 단계적 작업 시작 시간의 최소 간격(분) |
| max_interval | integer | No | 0 | 단계적 작업 시작 시간의 최대 간격(분) |
| start_time | string | No | — | 첫 번째 작업 시작 시간(HH:MM 형식) |
| rotate_proxy | boolean | No | false | 실행 전 기기 프록시 교체 |
| switch_account_method | string | No | — | 멀티 계정 모드에서 계정 전환 방법(예: profile) |
| official_packages | string[] | No | [] | 실행을 이 공식 패키지로 제한(멀티 계정 모드) |
| clone_package_prefix | string | No | — | 이 접두사로 시작하는 패키지 이름의 클론 앱으로 실행 제한 |
| script_config | object | No | — | 데스크톱 저장 설정을 오버라이드하는 기능 토글/설정(아래 참조) |
데이터 유형은 데이터셋에서 가져옴
실행 요청에서 data_source_type을 전달할 필요가 없습니다 — 캠페인은 데이터셋의 data_type(usernames 또는 post_links)을 자동으로 사용합니다. 게시물 링크 데이터셋은 boost_posts 및 mass_comment 기능만 지원합니다.
script_config 오버라이드
script_config는 선택 사항입니다. 생략하면 데스크톱 앱에서 구성한 기능 토글과 설정이 사용됩니다. 완전히 독립적인 캠페인을 실행하거나 특정 필드를 오버라이드하려면 제공하세요. 키는 camelCase와 snake_case 모두 허용됩니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| access_method | string | 사용자 이름 타겟 접근 방법: search 또는 direct |
| features.follow_users | boolean | 각 타겟 팔로우 |
| features.unfollow_users | boolean | 각 타겟 언팔로우 |
| features.report_account | boolean | 각 타겟 계정 신고 |
| features.send_dm | boolean | 각 타겟에 DM 전송 |
| features.boost_posts | boolean | 타겟의 게시물 좋아요/즐겨찾기/리포스트/공유 |
| features.mass_comment | boolean | 타겟의 게시물에 댓글 |
| follow_settings.boost_type | string | follow 또는 unfollow |
| dm_settings.message_format | string | multiline(기본값) 또는 spintax — 아래 DM 메시지 형식 참고 |
| dm_settings.message_contents | string | DM 본문. multiline에서는 각 줄이 개별 메시지(### = 메시지 내 줄바꿈), spintax에서는 문자열 전체가 하나의 메시지(입력 그대로의 줄바꿈, {option1|option2} 그룹). {username}와 {sender_username}를 지원합니다. |
| dm_settings.message_order | string | random 또는 sequential (multiline 형식에만 적용) |
| dm_settings.insert_emoji | boolean | DM에 랜덤 이모지 삽입 |
| dm_settings.generate_by_chatgpt | boolean | ChatGPT로 DM 생성 |
| dm_settings.chatgpt_prompt | string | DM 생성 시 사용할 프롬프트 |
| dm_settings.chatgpt_settings | object | { url, api_key, model, system_prompt } |
| post_settings.skip_posts_count | integer | 액션 전 건너뛸 게시물 수(0~8, 사용자 이름 소스만) |
| post_settings.max_posts_count | integer | 타겟당 처리할 최대 게시물 수 |
| post_settings.enable_like | boolean | 게시물 좋아요 |
| post_settings.enable_favorite | boolean | 게시물 즐겨찾기에 추가 |
| post_settings.enable_repost | boolean | 게시물 리포스트 |
| post_settings.enable_share | boolean | 게시물 공유 |
| post_settings.repeat_times | integer | 게시물 액션 반복 횟수 |
| post_settings.view_durations | integer[] | 각 게시물 시청 [min, max] 초 |
| comment_settings.comment_content | string | 댓글 텍스트(여러 변형은 줄바꿈으로 구분) |
| comment_settings.comment_order | string | random 또는 sequential |
| comment_settings.insert_emoji | boolean | 댓글에 랜덤 이모지 삽입 |
| comment_settings.generate_by_chatgpt | boolean | ChatGPT로 댓글 생성 |
| comment_settings.chatgpt_settings | object | { url, api_key, model, system_prompt } |
| task_finish_wait_time | integer | 완료 전 대기 초(데이터 손실 방지) |
DM 메시지 형식
dm_settings.message_contents는 dm_settings.message_format에 따라 해석되며, 게시물 캡션이 caption_format으로 해석되는 방식과 동일합니다:
| 형식 | 템플릿 | 줄바꿈 | 무작위 변형 |
|---|---|---|---|
multiline (기본값) | 비어 있지 않은 줄마다 하나, message_order로 선택 | 줄 안의 ### | 여러 줄에 걸쳐 message_order로 |
spintax | 문자열 전체가 단일 템플릿 | 문자열 안의 \n | {option1|option2} 그룹 |
{username}와 {sender_username}는 spintax 그룹 해석 전에 치환되므로, 변수가 옵션이 하나뿐인 spintax 그룹으로 처리되는 일은 없습니다.
// multiline
"dm_settings": {
"message_format": "multiline",
"message_contents": "Hey {username}! Love your content 🙌\nHi {username}###Here is a video I made###v.example.com/{username}",
"message_order": "sequential"
}
// spintax
"dm_settings": {
"message_format": "spintax",
"message_contents": "{Hi|Hello} {username}\n\nHere is a video I made\n\nv.example.com/{username}"
}
예제
최소 실행(데스크톱 저장 설정 사용)
curl -X POST http://localhost:50809/api/v1/super-marketing/run \
-H "Content-Type: application/json" \
-d '{
"serials": ["device_serial_1", "device_serial_2"],
"dataset_id": 7
}'
독립적인 팔로우 + DM 캠페인
curl -X POST http://localhost:50809/api/v1/super-marketing/run \
-H "Content-Type: application/json" \
-d '{
"serials": ["device_serial_1"],
"dataset_id": 7,
"enable_multi_account": true,
"min_interval": 1,
"max_interval": 3,
"script_config": {
"access_method": "search",
"features": {
"follow_users": true,
"send_dm": true
},
"follow_settings": { "boost_type": "follow" },
"dm_settings": {
"message_format": "multiline",
"message_contents": "안녕하세요! 콘텐츠가 정말 좋아요 🙌\n대단한 게시물이에요, 계속해주세요!",
"message_order": "random",
"insert_emoji": true
}
}
}'
게시물 링크 데이터셋에 대량 댓글
curl -X POST http://localhost:50809/api/v1/super-marketing/run \
-H "Content-Type: application/json" \
-d '{
"serials": ["device_serial_1"],
"dataset_id": 9,
"merge_same_username_tasks": true,
"script_config": {
"features": { "mass_comment": true },
"comment_settings": {
"comment_content": "🔥🔥🔥\n대박!\n너무 좋아요",
"comment_order": "random"
}
}
}'
응답 예제
{
"code": 0,
"message": "success",
"data": { "created_count": 6 }
}
created_count는 생성된 작업 수입니다. 대기 중인 작업은 다른 작업과 마찬가지로 할당된 기기에서 실행됩니다 — 작업 관리 API로 추적하세요.
오류 응답
| HTTP 상태 | 코드 | 설명 |
|---|---|---|
| 400 | 40001 | 유효하지 않은 매개변수(잘못된 data_type/strategy, 빈 serials, 비양수 dataset_id, 객체가 아닌 script_config, 또는 생성된 작업 없음) |
| 403 | 40301 | 금지 — API 액세스에는 Pro+ 플랜 필요 |
| 404 | 40401 | 데이터셋을 찾을 수 없음 |
| 500 | 50001 | 내부 서버 오류 |
작업이 생성되지 않는 경우
실행이 코드 40001과 "작업이 생성되지 않았습니다" 메시지를 반환하면, 데이터셋에 남은 타겟이 있는지(consume_once 전략의 경우) 그리고 선택한 기기가 온라인 상태인지 확인하세요.