Post 스크립트 설정

Threads 업데이트\nThreads는 이제 텍스트 전용 게시물(content_type = 2)을 지원합니다. 이 값은 Threads에서만 사용할 수 있으며 동영상, 이미지, 임시 저장 기능은 그대로입니다.\n:::

이 페이지는 작업 생성에서 사용되는 post 스크립트의 설정 매개변수를 기록합니다.

개요

post 스크립트는 TikTok, Instagram, Threads에 자동으로 동영상 또는 이미지를 게시하는 데 사용됩니다. TikTok과 Instagram은 플랫폼별 게시 방식 및 음성 옵션을 지원하며, Threads는 캡션이 있는 미디어 게시물 및 초안 저장을 지원합니다.

요청 매개변수

작업을 생성할 때 다음과 같은 최상위 매개변수를 지정할 수 있습니다:

매개변수	유형	필수	기본값	설명
serials	string[]	조건부 필수	[]	기기 일련번호 목록 (모드 1: 기기 기반)
usernames	string[]	조건부 필수	[]	사용자명 목록, 이러한 계정에 대한 작업을 직접 생성 (모드 2: 사용자명 기반)
script_name	string	예	-	실행할 스크립트 이름 (예: "post")
script_config	object	예	-	스크립트 설정 매개변수 (아래 참조)
enable_multi_account	boolean	아니오	false	다중 계정 모드 활성화 (기기의 각 계정에 대해 작업 생성)
start_time	string	아니오	-	선택 사항 시작 시간, 형식은 "HH:MM"
platform	string	조건부*	자동	대상 플랫폼: `tiktok`, `instagram`, `threads`. 아래 참고사항 참조

참고: serials 또는 usernames 중 하나를 제공해야 합니다.

*Platform 매개변수 동작:

TikMatrix 및 IgMatrix: platform 매개변수가 제공되어도 무시됩니다. 플랫폼은 앱 이름에서 자동으로 결정됩니다 (TikMatrix → tiktok, IgMatrix → instagram).
TikMatrix Pro: platform 매개변수는 필수이며 tiktok, instagram, 또는 threads로 명시적으로 지정해야 합니다.
Threads: 동영상/이미지 게시물, 여러 이미지, 캡션, 미디어 라이브러리 및 로컬 폴더를 포함한 두 가지 자료 소스, 그리고 save_draft를 지원합니다. Threads 앱이 이러한 TikTok/Instagram 흐름을 노출하지 않으므로 사운드, 상품 링크, 게시 위치, 커버, AI 라벨, 스토리 링크, 네이티브 예약 설정은 무시됩니다.

스크립트 설정 (`script_config`)

script_config 객체는 게시 스크립트의 매개변수를 포함합니다. 다음은 사용 가능한 매개변수입니다:

일반 매개변수 (TikTok, Instagram & Threads)

매개변수	유형	필수	기본값	설명
content_type	integer	아니오	0	콘텐츠 유형: `0` = 동영상, `1` = 이미지
image_count	integer	아니오	1	선택할 이미지 수 (content_type = 1일 때)
captions	string	아니오	""	게시물 캡션 텍스트. spintax 형식 지원: `{옵션1\|옵션2\|옵션3}`
caption_format	string	아니오	"multiline"	여러 줄 캡션 처리 방법: `multiline` (실제 줄바꿈 삽입) 또는 `singleline` (`\n`을 공백으로 대체)
ai_label	boolean	아니오	false	게시물에 AI 생성 콘텐츠 레이블 추가 여부
save_draft	boolean	아니오	false	TikTok(일반 동영상)과 Threads 전용입니다. 즉시 게시하는 대신 게시물을 임시저장으로 저장. Instagram과 TikTok 스토리(`placement = "story"`)에는 임시저장 옵션이 없으므로, 여기에 설정한 작업은 게시되지 않고 오류 `40001`로 거부됩니다.
post_way	string	아니오	"addButton"	게시 방식입니다. 자세한 내용은 아래의 게시 방법 섹션을 참조하세요
material_source	string	아니오	"materialLibrary"	소재 출처: `materialLibrary` (소재 라이브러리) 또는 `localFolder` (로컬 폴더), material_list가 제공된 경우 무시됨
material_path	string	조건부 필수	""	로컬 폴더 경로 (material_source = "localFolder"일 때 필수)
material_list	string[]	아니오	[]	소재 파일 경로 배열을 직접 전달합니다. 이 매개변수를 제공할 때 material_source 및 material_path 로직을 건너뜁니다. API 자동화 시나리오에 권장됩니다.
materials_tags	string	아니오	""	소재 라이브러리에서 필터링하기 위한 쉼표로 구분된 소재 태그
upload_wait_time	integer	아니오	10	업로드 완료 대기 시간 (초)
upload_wait_time_min	integer	아니오	-	대기 시간 범위의 하한값. 상한과 하한을 모두 설정하면 스크립트가 작업마다 범위 내에서 무작위 값을 선택합니다
upload_wait_time_max	integer	아니오	-	대기 시간 범위의 상한값
sound_wait_time	integer	아니오	10	음성 로드 대기 시간 (초)
sound_wait_time_min	integer	아니오	-	대기 시간 범위의 하한값. 상한과 하한을 모두 설정하면 스크립트가 작업마다 범위 내에서 무작위 값을 선택합니다
sound_wait_time_max	integer	아니오	-	대기 시간 범위의 상한값
add_sound	string/integer	아니오	"-1"	음성 옵션: `-1` = 기본값, `0` = 비활성화, `1` = 활성화, `custom` = 사용자 지정 음성 사용
sound_name	string	조건부 필수	""	음성 이름/URL (post_way = "useSound"일 때 필수)
custom_sound_keyword	string	조건부 필수	""	사용자 지정 음성 검색 키워드 (add_sound = "custom"일 때 필수)
origin_sound_volume	integer	아니오	100	원본 음성 볼륨 (0-100)
add_sound_volume	integer	아니오	100	추가 음성 볼륨 (0-100)

upload_wait_time 는 일반 게시와 save_draft 초안 모드 모두에 적용됩니다. 초안으로 저장하더라도 TikTok/Threads 이 백그라운드에서 동영상 업로드를 마칠 시간이 필요합니다.

upload_wait_time과 sound_wait_time은 범위 지정도 지원합니다. upload_wait_time_min / upload_wait_time_max(또는 sound_wait_time_min / sound_wait_time_max)를 전달하면 스크립트가 작업마다 해당 범위 안에서 새로운 무작위 값을 선택하므로 모든 작업이 같은 시간을 기다리지 않습니다. 두 경계가 모두 있으면 범위가 우선하며, 그렇지 않으면 단일 값 키가 사용됩니다.

게시 방법 (`post_way`)

post_way 매개변수는 스크립트가 게시 화면을 여는 방식을 제어합니다:

값	설명
`addButton`	(기본값) 앱 내 "+" 만들기 버튼을 탭한 다음 기기 갤러리에서 미디어를 선택합니다. 모든 게시 위치(`reel`, `story`, `post`)에서 작동합니다. 대부분의 경우에 권장됩니다.
`share`	미디어 파일에서 Instagram/TikTok 앱으로 Android 공유 인텐트를 직접 실행합니다. 앱 내 탐색을 우회하는 대체 방법으로, 특정 기기나 앱 버전에서 `addButton` 흐름이 불안정할 때 유용합니다.
`useSound`	먼저 특정 오디오 트랙으로 이동한 다음(`sound_name` URL 또는 키워드 사용) 그 사운드에 동영상을 연결합니다. Reels / TikTok 전용입니다. `sound_name` 설정이 필요합니다. `placement = "post"` 또는 `placement = "story"`와는 호환되지 않습니다.

노트

placement가 post(Instagram 피드 게시물)인 경우 post_way와 관계없이 사운드 자동화는 지원되지 않습니다. 스크립트가 사운드 단계를 자동으로 건너뜁니다.

TikTok 전용 매개변수

매개변수	유형	필수	기본값	설명
placement	string	아니오	""	게시 위치: `""` (일반 비디오, 기본값) 또는 `"story"` (TikTok Story). `"story"` 설정 시 스크립트는 사운드 설정 후 "Your Story"를 클릭하여 제목/상품 링크/AI 라벨 단계를 건너뜁니다.
add_product_link	integer	아니오	0	상품/쇼핑 링크 추가 여부: `0` = 아니오, `1` = 예

Instagram 전용 매개변수

매개변수	유형	필수	기본값	설명
placement	string	아니오	"reel"	게시 위치: `reel`(Reels), `story`(스토리), 또는 `post`(일반 피드 게시물). 참고: `placement`가 `post`일 때는 사운드 옵션이 지원되지 않습니다
enable_schedule_reels	boolean	아니오	false	Reel을 미래 시간으로 예약할지 여부
schedule_reels_time	string	조건부 필수	""	`YYYY-MM-DD HH:MM` 형식의 예약 게시 시간 (enable_schedule_reels = true일 때 필수)
trial_reel	boolean	아니오	false	Instagram의 "체험용 릴스" 스위치를 켤지 여부입니다. 릴스는 먼저 팔로워가 아닌 사람에게 표시되며 프로필에는 나타나지 않습니다 (placement = "reel"인 경우에만 적용). 이 옵션이 없는 계정은 일반 릴스로 게시됩니다
story_link	string	아니오	""	Story에 스티커 링크로 첨부할 URL (placement = "story"일 때만 적용)

예제

기본 게시 작업 - 소재 경로 직접 전달

이것은 API 자동화의 권장 방식입니다 - 소재 라이브러리나 폴더 스캔에 의존하지 않고 소재 파일 경로를 직접 전달합니다:

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": "내 새로운 동영상을 확인해보세요! #viral #fyp",
      "material_list": [
        "C:/Videos/video1.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

소재 라이브러리를 사용한 게시 (TikTok)

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": 0,
      "captions": "내 새로운 동영상을 확인해보세요! #viral #fyp",
      "post_way": "addButton",
      "material_source": "materialLibrary",
      "materials_tags": "trending, dance",
      "upload_wait_time": 60,
      "add_sound": "-1"
    },
    "enable_multi_account": false
  }'

사용자명 목록으로 게시 작업 생성

이 모드를 사용하면 기기 일련번호를 알 필요 없이 특정 계정에 대한 작업을 직접 생성할 수 있습니다:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["@user1", "@user2", "@user3"],
    "script_name": "post",
    "script_config": {
      "content_type": 0,
      "captions": "내 새로운 동영상을 확인해보세요! #viral #fyp",
      "material_list": [
        "C:/Videos/video1.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

TikTok Story 게시

TikTok Story에 직접 게시합니다. 스크립트는 음성 설정 완료 후 "Your Story"를 클릭합니다 — 캡션/상품 링크/AI 라벨 단계 없음:

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,
      "placement": "story",
      "post_way": "addButton",
      "material_list": ["C:/Videos/story_video.mp4"],
      "upload_wait_time": 30
    }
  }'

로컬 폴더를 사용한 게시 (Instagram Reel)

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": "놀라운 콘텐츠! #instagram #reels",
      "post_way": "addButton",
      "placement": "reel",
      "material_source": "localFolder",
      "material_path": "C:/Videos/instagram",
      "upload_wait_time": 45
    },
    "enable_multi_account": true
  }'

Instagram 피드 게시물 (placement: post)

일반 Instagram 피드(릴이 아님)에 게시합니다. 이 위치에서는 사운드 옵션이 지원되지 않습니다:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "platform": "instagram",
    "script_config": {
      "content_type": 0,
      "captions": "New post! #instagram",
      "placement": "post",
      "post_way": "addButton",
      "material_list": ["C:/Videos/my_video.mp4"],
      "upload_wait_time": 45
    }
  }'

사용자 지정 음성으로 게시

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": "이 트렌디한 음성으로 춤을 춥니다!",
      "post_way": "addButton",
      "add_sound": "custom",
      "custom_sound_keyword": "trending dance 2024",
      "origin_sound_volume": 30,
      "add_sound_volume": 70,
      "material_source": "materialLibrary",
      "upload_wait_time": 60
    }
  }'

특정 음성 URL을 사용한 게시

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "script_config": {
      "post_way": "useSound",
      "sound_name": "https://www.tiktok.com/music/original-sound-7123456789",
      "captions": "이 멋진 음악을 사용합니다!",
      "material_source": "materialLibrary"
    }
  }'

이미지 게시 (캐러셀)

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": 1,
      "image_count": 5,
      "captions": "이 사진들을 확인해보세요! #photocarousel",
      "material_source": "localFolder",
      "material_path": "C:/Images/carousel",
      "upload_wait_time": 45
    }
  }'

명시적 플랫폼 선택으로 게시

platform 매개변수를 사용하여 대상 플랫폼을 명시적으로 지정할 수 있습니다. 이는 환경 기본값을 재정의해야 할 때 유용합니다:

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1"],
    "script_name": "post",
    "platform": "instagram",
    "script_config": {
      "content_type": 0,
      "captions": "Instagram에 게시! #instagram #reels",
      "placement": "reel",
      "material_list": [
        "C:/Videos/instagram_video.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

응답

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

개요​

요청 매개변수​

스크립트 설정 (script_config)​

일반 매개변수 (TikTok, Instagram & Threads)​

게시 방법 (post_way)​

TikTok 전용 매개변수​

Instagram 전용 매개변수​

예제​

기본 게시 작업 - 소재 경로 직접 전달​

소재 라이브러리를 사용한 게시 (TikTok)​

사용자명 목록으로 게시 작업 생성​

TikTok Story 게시​

로컬 폴더를 사용한 게시 (Instagram Reel)​

Instagram 피드 게시물 (placement: post)​

사용자 지정 음성으로 게시​

특정 음성 URL을 사용한 게시​

이미지 게시 (캐러셀)​

명시적 플랫폼 선택으로 게시​

응답​

관련 문서​

개요