슈퍼 마케팅 스크립트 구성
이 페이지에서는 슈퍼 마케팅 스크립트의 API 엔드포인트를 설명합니다. 다른 스크립트와 달리, 슈퍼 마케팅은 일반 POST /api/v1/task 엔드포인트를 통해 생성하지 않습니다 — 재사용 가능한 타겟 데이터셋을 기반으로 실행되며 전용 엔드포인트가 있습니다.
개요
슈퍼 마케팅 캠페인은 타겟 풀에 대해 여러 성장 액션(팔로우, 언팔로우, 신고, DM, 부스트, 대량 댓글)을 한 번에 결합하여 실행합니다. 타겟 풀은 데이터셋으로 저장됩니다:
- 데이터 유형 — 데이터셋에는
usernames(TikTok/Instagram 핸들) 또는post_links(게시물 URL)가 포함됩니다. - 전략 — 타겟을 기기에 배분하는 방식을 제어합니다:
shared_pool— 선택한 모든 기기/계정이 모든 타겟을 처리합니다.consume_once— 타겟을 기기 간에 분할하여 각 타겟을 한 번만 처리합니다.
일반적인 흐름:
- 타겟을 데이터셋에 가져오기 →
dataset_id획득. dataset_id를 참조하는 캠페인을 하나 이상의 기기에서 실행.
기능 토글(팔로우 / DM / 댓글 등)과 세부 설정은 데스크톱 앱의 저장된 구성(super_marketing_settings.json)에서 읽어옵니다. 실행 요청에 script_config를 전달하여 실행별로 오버라이드할 수 있습니다.
라이선스 요구 사항
모든 슈퍼 마케팅 엔드포인트는 로컬 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 전략의 경우) 그리고 선택한 기기가 온라인 상태인지 확인하세요.