Post 脚本配置

本页面记录了任务创建中使用的 post 脚本的配置参数。

概述

post 脚本用于自动发布内容（视频或图片）到 TikTok 或 Instagram。它支持多种发布方式、素材来源和音频选项。

请求参数

创建任务时，可以指定以下顶级参数：

参数	类型	必需	默认值	描述
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. 아래 참고사항 참조

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

*Platform 매개변수 동작:

• TikMatrix 및 IgMatrix: platform 매개변수가 제공되어도 무시됩니다. 플랫폼은 앱 이름에서 자동으로 결정됩니다 (TikMatrix → tiktok, IgMatrix → instagram).
• TikMatrix Pro: platform 매개변수는 필수이며 tiktok 또는 instagram으로 명시적으로 지정해야 합니다.

脚本配置 (script_config)

script_config 对象包含发布脚本的参数。以下是可用参数：

通用参数（TikTok 和 Instagram）

参数	类型	必需	默认值	描述
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	즉시 게시하는 대신 게시물을 임시저장으로 저장
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 는 일반 게시와 save_draft 초안 모드 모두에 적용됩니다. 초안으로 저장하더라도 TikTok/Instagram 이 백그라운드에서 동영상 업로드를 마칠 시간이 필요합니다. | sound_wait_time | integer | 否 | 10 | 等待音频加载的秒数 | | 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） |

게시 방법 (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일 때 필수)
story_link	string	否	""	Story에 스티커 링크로 첨부할 URL (placement = "story"일 때만 적용)

示例

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
    }
  }'

基础发布任务 - 直接传递素材路径

这是 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": "看看我的新视频！#热门 #推荐",
      "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": "看看我的新视频！#热门 #推荐",
      "post_way": "addButton",
      "material_source": "materialLibrary",
      "materials_tags": "热门, 舞蹈",
      "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": "看看我的新视频！#热门 #推荐",
      "material_list": [
        "C:/Videos/video1.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

使用本地文件夹发布（Instagram）

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": "热门舞曲 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": "看看这些照片！#图集",
      "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
  }
}

相关文档

• 任务管理 API - 创建、列表和管理任务