Post Script Configuration

This page documents the configuration parameters for the post script used in task creation.

Overview

The post script is used to automatically publish content (videos or images) to TikTok or Instagram. It supports various posting methods, material sources, and sound options.

Request Parameters

When creating a task, you can specify the following top-level parameters:

Parameter	Type	Required	Default	Description
serials	string[]	Conditional	[]	List of device serial numbers (Mode 1: device-based)
usernames	string[]	Conditional	[]	List of usernames to create tasks for (Mode 2: username-based)
script_name	string	Yes	-	Script name to execute (e.g., "post")
script_config	object	Yes	-	Script configuration parameters (see below)
enable_multi_account	boolean	No	false	Enable multi-account mode (create task for each account on device)
start_time	string	No	-	Optional start time in format "HH:MM"
platform	string	Conditional*	auto	Target platform: `tiktok`, `instagram`. See note below

Note: Either serials or usernames must be provided.

*Platform Parameter Behavior:

TikMatrix & IgMatrix: The platform parameter is ignored if provided. The platform is automatically determined from the app name (TikMatrix → tiktok, IgMatrix → instagram).
TikMatrix Pro: The platform parameter is required and must be explicitly specified as either tiktok or instagram.

Script Configuration (`script_config`)

The script_config object contains the parameters for the post script. Below are the available parameters:

Common Parameters (TikTok & Instagram)

Parameter	Type	Required	Default	Description
content_type	integer	No	0	Content type: `0` = Video, `1` = Images
image_count	integer	No	1	Number of images to select (when content_type = 1)
captions	string	No	""	Caption text for the post. Supports spintax format: `{option1\|option2\|option3}`
caption_format	string	No	"multiline"	How to handle multi-line captions: `multiline` (insert real newlines) or `singleline` (replace `\n` with spaces)
post_way	string	No	"addButton"	Post method. See Post Methods section below for details
material_source	string	No	"materialLibrary"	Material source: `materialLibrary` or `localFolder` (ignored if material_list is provided)
material_path	string	Conditional	""	Local folder path (required when material_source = "localFolder")
material_list	string[]	No	[]	Direct material file paths array. When provided, bypasses material_source and material_path logic. Ideal for API automation.
materials_tags	string	No	""	Comma-separated material tags for filtering from library
upload_wait_time	integer	No	10	Seconds to wait for upload completion
sound_wait_time	integer	No	10	Seconds to wait for sound loading
add_sound	string/integer	No	"-1"	Sound option: `-1` = default, `0` = disable, `1` = enable, `"custom"` = use custom sound
sound_name	string	Conditional	""	Sound name/URL (required when post_way = "useSound")
custom_sound_keyword	string	Conditional	""	Keyword to search for custom sound (required when add_sound = "custom")
origin_sound_volume	integer	No	100	Original sound volume (0-100)
add_sound_volume	integer	No	100	Added sound volume (0-100)
ai_label	boolean	No	false	Whether to add the AI-generated content label to the post
save_draft	boolean	No	false	Save the post as a draft instead of publishing immediately

upload_wait_time applies to both normal posting and save_draft mode. Even when saving as a draft, TikTok/Instagram still needs time to finish uploading the video in the background.

Post Methods (`post_way`)

The post_way parameter controls how the script opens the posting screen:

Value	Description
`addButton`	(Default) Taps the in-app "+" create button, then selects media from the device gallery. Works with all placements (`reel`, `story`, `post`). Recommended for most cases.
`share`	Triggers an Android share intent directly from the media file to the Instagram/TikTok app. An alternative method that bypasses in-app navigation; useful when the `addButton` flow is unreliable on a particular device or app version.
`useSound`	Navigates to a specific audio track first (via `sound_name` URL or keyword), then attaches the video to that sound. For Reels / TikTok only. Requires `sound_name` to be set. Not compatible with `placement = "post"` or `placement = "story"` on Instagram.

note

When placement is post (Instagram feed post), sound automation is not supported regardless of post_way. The script will skip the sound step automatically.

TikTok Specific Parameters

Parameter	Type	Required	Default	Description
placement	string	No	""	Post placement: `""` (normal video, default) or `"story"` (TikTok Story). When set to `"story"`, the script clicks "Your Story" after the sound setup step and skips the caption/product link/AI label flow.
add_product_link	integer	No	0	Whether to add a product/shopping link: `0` = no, `1` = yes

Instagram Specific Parameters

Parameter	Type	Required	Default	Description
placement	string	No	"reel"	Post placement: `reel` (Reels), `story` (Stories), or `post` (regular feed post). Note: sound options are not supported when `placement` is `post`
enable_schedule_reels	boolean	No	false	Whether to schedule the Reel for a future time
schedule_reels_time	string	Conditional	""	Scheduled publish time in format `YYYY-MM-DD HH:MM` (required when enable_schedule_reels = true)
story_link	string	No	""	URL to attach as a sticker link on a Story (only applies when placement = "story")

Examples

Basic Post Task with Direct Material List

This is the recommended approach for API automation - pass material paths directly without relying on material library or folder scanning:

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": "Check out my new video! #viral #fyp",
      "material_list": [
        "C:/Videos/video1.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

Post Task with Material Library (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": "Check out my new video! #viral #fyp",
      "post_way": "addButton",
      "material_source": "materialLibrary",
      "materials_tags": "trending, dance",
      "upload_wait_time": 60,
      "add_sound": "-1"
    },
    "enable_multi_account": false
  }'

TikTok Story Post

Publish directly to TikTok Story. The script completes sound setup then clicks "Your Story" — skipping the caption/product link steps:

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

Post Task by Username List

This mode allows you to create tasks directly for specific accounts without knowing their device serial numbers:

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": "Check out my new video! #viral #fyp",
      "material_list": [
        "C:/Videos/video1.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

Post Task with Local Folder (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": "Amazing content! #instagram #reels",
      "post_way": "addButton",
      "placement": "reel",
      "material_source": "localFolder",
      "material_path": "C:/Videos/instagram",
      "upload_wait_time": 45
    },
    "enable_multi_account": true
  }'

Instagram Feed Post (placement: post)

Publish to the regular Instagram feed (non-Reel). Sound options are not supported for this placement:

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

Post with Custom Sound

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": "Dancing to this trending sound!",
      "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
    }
  }'

Post Using Specific Sound 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": "Using this awesome sound!",
      "material_source": "materialLibrary"
    }
  }'

Post Images (Carousel)

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": "Check out these photos! #photocarousel",
      "material_source": "localFolder",
      "material_path": "C:/Images/carousel",
      "upload_wait_time": 45
    }
  }'

Post with Explicit Platform Selection

You can explicitly specify the target platform using the platform parameter. This is useful when you want to override the environment default:

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": "Posting to Instagram! #instagram #reels",
      "placement": "reel",
      "material_list": [
        "C:/Videos/instagram_video.mp4"
      ],
      "upload_wait_time": 60
    }
  }'

Response

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

Overview​

Request Parameters​

Script Configuration (script_config)​

Common Parameters (TikTok & Instagram)​

Post Methods (post_way)​

TikTok Specific Parameters​

Instagram Specific Parameters​

Examples​

Basic Post Task with Direct Material List​

Post Task with Material Library (TikTok)​

TikTok Story Post​

Post Task by Username List​

Post Task with Local Folder (Instagram Reel)​

Instagram Feed Post (placement: post)​

Post with Custom Sound​

Post Using Specific Sound URL​

Post Images (Carousel)​

Post with Explicit Platform Selection​

Response​

See Also​