SocialEcho OpenAPI Documentation

Last updated: 2026-08-28

1. Intended Audience

This document is intended for development, QA, implementation, and automation engineers integrating with the SocialEcho external API. Its goal is to help you complete a working integration in the shortest possible time.

This document covers teams, accounts, authorization links, posts, reports, OSS uploads, Reddit/Pinterest publishing resources, TikTok Shop products and music, and cross-platform publishing under a Team API Key. Brand, AI generation, and document management APIs are outside the scope of this version.

2. Quick Start (3 Minutes)

1. Sign in at https://app.socialecho.net and create a team.
2. Create a Team API Key under "Team Management".
3. Call the API using Bearer authentication (Authorization: Bearer se_xxx).
4. Call GET /v1/team first to verify authentication and the team context, then call other business endpoints.
5. Use the HTTP status code to determine the request result, then use the business code in the response to identify the specific cause.

3. Environment and Authentication

3.1 GET Request Parameter Rules

Business parameters for all GET endpoints must be placed in the QueryString; requests must not include a body. Use bracket notation for array parameters, for example, account_ids[]=1&account_ids[]=2. When CloudFront receives a GET request with a body, it returns an HTML 403 Bad request directly.

3.2 Recommended Success Criteria

• Successful response: the HTTP status code is 200-299, and code in the response JSON must be 0. All endpoints listed in this document currently return HTTP 200 on normal success.
• Failed response: the HTTP status code is 400-599, and code in the response JSON is a non-zero business code. Business failures are no longer returned as HTTP 200.
• The client should first branch on the HTTP status code, then use the business code, error.type, and data for detailed handling.
• For a non-2xx response, the client should still parse the JSON response body and record request_id; do not treat every non-2xx response as an unparseable network error.
• Success from a publishing endpoint only means that the task was submitted successfully; the final publishing result is determined by the asynchronous task and platform review.

3.3 Unified Response Structure

Successful response example:

{
  "code": 0,
  "message": "Success",
  "data": {},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

Failed response example:

{
  "code": 42200,
  "message": "Request parameter validation failed",
  "data": {
    "account_id": ["Please select a TikTok Shop account"]
  },
  "error": {
    "type": "invalid_request",
    "reason": "Request parameter validation failed",
    "suggestion": "Check the request parameters and try again"
  },
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

The server also returns X-Request-Id in the response header. Callers may provide a valid X-Request-Id themselves or use the server-generated value to correlate logs. Successful paginated responses also include meta.

4. General Error Handling Strategy

Standard business codes use the form "HTTP status code x 100". A few historical business scenarios may retain a more specific custom non-zero code; this does not change the meaning of the HTTP status code, and callers should not rely on a single business code to determine success or failure.

Automatic retries are recommended only for 429, 502, 503, 504, and network timeouts. 400, 401, 403, 404, 405, 409, 413, and 422 usually require correcting the request, permissions, or resource state first.

5. Endpoint List

The Base URL in all examples below is https://api.socialecho.net. Replace se_your_team_api_key with your Team API Key.

GET examples do not send Content-Type or a request body; when parameters are required, append them directly to the QueryString.

5.1 Get Team Information Accessible by the Current API Key (GET /v1/team)

It is recommended to call this endpoint first to confirm the team context before retrieving business data.

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Retrieved successfully",
  "data": {
    "id": 1024,
    "code": "TEAM_ABC123",
    "title": "SocialEcho QA Team",
    "thumb": "https://oss.socialecho.net/team/TEAM_ABC123/avatar.jpg",
    "describe": "SocialEcho API integration team",
    "created_at": "2026-08-01 02:30:00 UTC",
    "timezone": {
      "id": 45,
      "name": "Asia/Shanghai",
      "offset": "UTC+08:00",
      "city": "Shanghai"
    }
  },
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

5.2 Get the Social Media Account List (GET /v1/account)

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/account?page=1&type=1' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Retrieved successfully",
  "data": [{
    "id": 163751,
    "title": "example_account",
    "account": "example_account",
    "url": "https://www.tiktok.com/@example_account",
    "app": {"id": 11, "title": "TikTokShop"},
    "type": {"value": 1, "label": "Owned account"},
    "status": {"value": 1, "label": "Normal"}
  }],
  "meta": {"total": 1, "current_page": 1, "last_page": 1, "per_page": 15},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

5.3 Get Platform Authorization Links (GET /v1/oauth/links)

Get the social media platform authorization entry points available to the current team. The endpoint returns one or more connection methods per platform. Callers can select an authorization URL based on data[].id, data[].title, and connections[].type.

This endpoint has no business parameters.

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/oauth/links' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example (excerpt; URLs redacted)

{
  "code": 0,
  "message": "Retrieved successfully",
  "data": [
    {
      "id": 1,
      "title": "Instagram",
      "connections": [
        {
          "type": "instagram",
          "url": "https://authorization.example/instagram"
        },
        {
          "type": "facebook",
          "url": "https://authorization.example/facebook"
        }
      ]
    },
    {
      "id": 3,
      "title": "TikTok",
      "connections": [
        {
          "type": "personal",
          "url": "https://authorization.example/tiktok"
        }
      ]
    },
    {
      "id": 11,
      "title": "TikTokShop",
      "connections": [
        {
          "type": "seller",
          "url": "https://authorization.example/tiktokshop/seller"
        },
        {
          "type": "creator",
          "url": "https://authorization.example/tiktokshop/creator"
        }
      ]
    }
  ],
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

Response fields:

Currently returned platforms and connection types:

Open the authorization URL exactly as returned by the endpoint; do not rewrite it or discard query parameters. The URL may contain team-related state information, so long-term caching, public sharing, and writing it to ordinary business logs are not recommended. Call this endpoint again whenever authorization is required.

5.4 Get the Post List (GET /v1/article)

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/article?page=1&account_ids[]=163956&account_ids[]=163955&account_ids[]=28' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": [{
    "id": 987654,
    "uuid": "platform_post_id",
    "title": null,
    "content": "Example article content",
    "url": "https://www.example.com/post/platform_post_id",
    "app": {"id": 3, "title": "TikTok"},
    "created_at": "2026-08-27 13:00:00 +08:00",
    "updated_at": "2026-08-27 13:05:00 +08:00",
    "account": {
      "id": 163751,
      "avatar": "https://oss.socialecho.net/account/avatar.jpg",
      "account": "example_account",
      "title": "Example Account",
      "url": "https://www.tiktok.com/@example_account"
    },
    "report": {
      "exposure": 1021,
      "like": 40,
      "comment": 14,
      "share": 0,
      "quote": 0,
      "favorite": 12
    },
    "attachments": [{
      "id": 456789,
      "url": "https://oss.socialecho.net/team/TEAM_ABC123/20260827/example.mp4",
      "thumb": null,
      "type": "video",
      "iframe": null
    }],
    "quote": null
  }],
  "meta": {"total": 1, "current_page": 1, "last_page": 1, "per_page": 15},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

5.5 Get Report Data (GET /v1/report)

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/report?start_date=2026-01-01&end_date=2026-03-24&time_type=1&account_ids[]=163956&account_ids[]=163955&account_ids[]=28' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

group changes the structure of data. Callers must parse the response according to the group in the request and must not assume that every grouping returns the same structure.

Response example (without group, aggregate)

{
  "code": 0,
  "message": "Success",
  "data": {
    "total": {
      "fans": 5320,
      "content": 84,
      "exposure": 120345,
      "comment": 893,
      "like": 4512,
      "share": 326,
      "quote": 12,
      "favorite": 645
    },
    "increase": {
      "fans": 102,
      "content": 14,
      "exposure": 18340,
      "comment": 116,
      "like": 507,
      "share": 38,
      "quote": 3,
      "favorite": 72
    }
  },
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

Response structure (group=day, excerpt)

{
  "code": 0,
  "message": "Success",
  "data": [{
    "date": "2026-03-23",
    "total": {"fans": 5310, "content": 6, "exposure": 8421, "comment": 52, "like": 301, "share": 19, "quote": 1, "favorite": 34},
    "increase": {"fans": 12, "content": 6, "exposure": 8421, "comment": 52, "like": 301, "share": 19, "quote": 1, "favorite": 34}
  }],
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

With group=app, each item in data[] contains platform id, title, total, and increase. With group=account, each item contains account id, title, account, avatar, url, app, total, and increase. This endpoint currently defines only day, app, and account as grouping values; do not pass other values.

To retrieve daily data, add group=day to the request URL. Use group=app and group=account for platform and account grouping, respectively.

5.6 Get an OSS Upload URL (GET /v1/upload/url)

Get the presigned URL required to upload a file to OSS. The general flow is: obtain the upload URL -> upload the file using the returned HTTP method -> use public_url in the publishing endpoint's attachments.

content_type values:

• Images: image/jpeg, image/jpg, image/png, image/gif, image/webp, image/bmp.
• Videos: video/mp4, video/avi, video/mov, video/wmv, video/flv, video/webm, video/mkv, video/3gp, video/quicktime.
• Audio: audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/aac, audio/mp4, audio/m4a, audio/ogg, audio/webm, audio/flac.

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/upload/url?content_type=video%2Fmp4&title=product-video.mp4' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": {
    "upload_url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/AbCdEf1234567890AbCdEf1234567890.mp4?signature=example",
    "method": "PUT",
    "public_url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/AbCdEf1234567890AbCdEf1234567890.mp4",
    "object_key": "team/TEAM_ABC123/20260828/AbCdEf1234567890AbCdEf1234567890.mp4",
    "headers": {"Content-Type": "video/mp4"},
    "expire_in": 600,
    "file_id": 123456,
    "file": {
      "id": 123456,
      "url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/AbCdEf1234567890AbCdEf1234567890.mp4",
      "title": "product-video.mp4",
      "extension": "mp4",
      "mime": "video/mp4",
      "type": "video",
      "size": 0,
      "status": "pending",
      "extra": [],
      "created_at": "2026-08-28 10:00:00 +08:00",
      "updated_at": "2026-08-28 10:00:00 +08:00"
    }
  },
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

During upload, use the method, upload_url, and headers exactly as returned. upload_url is signed and time-limited; do not modify it, cache it, or use it for publishing.

File upload example

curl --request PUT 'upload_url_from_previous_response' \
  --header 'Content-Type: video/mp4' \
  --upload-file './product-video.mp4'

After a successful upload, the publishing endpoint must use the returned public_url, not the time-limited upload_url.

The upload endpoint supports audio files, but whether the publishing endpoint accepts an audio attachment still depends on the target platform and the publishing rules for type; a successful upload alone does not mean that the asset can be published.

This endpoint returns HTTP 200, code = 0 on success. Missing parameters, incorrect field types, or overlong fields return HTTP 422, code = 42200. An unexpected server error while generating the upload URL returns HTTP 500, code = 50000. Callers should submit only the MIME types listed above; the current server returns unsupported MIME types as HTTP 500, code = 50000.

5.7 Get the Reddit Community List (GET /v1/reddit/communities)

Use this endpoint to select the community context before publishing Reddit content.

curl --request GET 'https://api.socialecho.net/v1/reddit/communities?account_id=163751' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": [{
    "id": 301,
    "uuid": "t5_example",
    "title": "example-community",
    "attributes": {
      "description": "Example community",
      "avatar": "https://styles.redditmedia.com/example.png",
      "subscribers": 12000,
      "permissions": {
        "release": true,
        "type": ["text", "media", "link"]
      }
    },
    "created_at": "2026-08-28 10:00:00",
    "updated_at": "2026-08-28 10:00:00"
  }],
  "meta": {"total": 1, "current_page": 1, "last_page": 1, "per_page": 15},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

When publishing Reddit content, extra.category_id, if provided, must use the integer data[].id returned by this endpoint; do not pass uuid. Before submitting, check that attributes.permissions.release = true and confirm that the target type appears in attributes.permissions.type. The current community list does not guarantee that flair options are returned. If there is no confirmed valid flair, omit extra.flair instead of submitting an empty object.

5.8 Get the Pinterest Board List (GET /v1/pinterest/boards)

Use this endpoint to select a board before publishing Pinterest content.

curl --request GET 'https://api.socialecho.net/v1/pinterest/boards?account_id=163751' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": [{
    "id": 401,
    "uuid": "987654321012345678",
    "title": "Home Decor",
    "attributes": {},
    "created_at": "2026-08-28 10:00:00",
    "updated_at": "2026-08-28 10:00:00"
  }],
  "meta": {"total": 1, "current_page": 1, "last_page": 1, "per_page": 15},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

When publishing Pinterest content, extra.category_id must use the integer data[].id returned by this endpoint; do not pass the platform board uuid.

5.9 Get the TikTok Shop Product List (GET /v1/tiktokshop/products)

Get the products already synchronized for the specified TikTok Shop account. Before publishing TikTok Shop shoppable video or photo content, call this endpoint first to obtain the complete id, uuid, title, and thumb.

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/tiktokshop/products?account_id=123456&page=1&per_page=20&keyword=vase' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": [{
    "id": 789,
    "uuid": "1732443576158556877",
    "title": "Ceramic Flower Vase",
    "thumb": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product.jpg",
    "status": 1,
    "price": {"min": "68.88", "max": "68.88", "currency": "USD"}
  }],
  "meta": {"total": 1, "current_page": 1, "last_page": 1, "per_page": 20},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

status = 1 means that the product is currently available for publishing. If a Chinese keyword does not return a match, use the product's English title or omit keyword to retrieve all products.

5.9.1 Submit a TikTok Shop Product Synchronization Task (POST /v1/tiktokshop/products/sync)

Request that SocialEcho asynchronously refresh the products for the specified TikTok Shop account. This endpoint only indicates whether the synchronization task entered the queue successfully; it does not indicate that the products have finished refreshing. To avoid duplicate synchronization, the same account has an approximately 60-minute cooldown period.

curl --request POST 'https://api.socialecho.net/v1/tiktokshop/products/sync' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --data-raw '{"account_id":123456}'

Successful response:

{
  "code": 0,
  "message": "Product synchronization task submitted",
  "data": {
    "account_id": 123456,
    "status": "queued"
  },
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

5.10 Get TikTok Shop Music Genres (GET /v1/tiktokshop/music/genres)

Get the music categories supported by the trending music endpoint. This endpoint has no business parameters.

curl --request GET 'https://api.socialecho.net/v1/tiktokshop/music/genres' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example (excerpt)

{
  "code": 0,
  "message": "Success",
  "data": [
    {"value": "ALL", "label": "All"},
    {"value": "POP", "label": "Pop"},
    {"value": "BGM", "label": "Background Music"}
  ],
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

This endpoint returns HTTP 200, code = 0 on success. Business prerequisites such as insufficient credits return HTTP 422, code = 42200; an unexpected server error returns HTTP 500, code = 50000. Authentication failures, incorrect request methods, and other cases follow the general status code rules in Section 4.

5.11 Get Trending TikTok Shop Music (GET /v1/tiktokshop/music/trending)

Get available music from the TikTok commercial music library. account_id can be the ID of a TikTok Shop account that is currently in a normal state for the team, or a TikTok authorized account ID directly. When a TikTok Shop account is provided, the server resolves its associated or available TikTok authorized account to query music.

Request example (cURL)

curl --request GET 'https://api.socialecho.net/v1/tiktokshop/music/trending?account_id=123456&country_code=US&genre=BGM&date_range=7DAY' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Accept: application/json' \
  --header 'X-Lang: en'

Response example

{
  "code": 0,
  "message": "Success",
  "data": [{
    "uuid": "6817383821571262465",
    "title": "A lovely acoustic song",
    "artist": "Hiraoka",
    "url": "https://example.tiktokcdn.com/music",
    "cover": "https://example.tiktokcdn.com/cover.jpeg",
    "duration": 81
  }],
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

The returned fields in data[] are:

selection, music_volume, and original_sound_volume are not response fields from the music list endpoint; they are music control parameters set by the caller when publishing. When publishing with selected music, copy the six fields url, uuid, cover, title, artist, and duration returned by the music list into extra.music without changing their values, then add the three publishing control fields selection, music_volume, and original_sound_volume. Do not pass only the music UUID or reduce the object to four fields.

Complete music object example

{
  "url": "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2102/oUNQD7eSEFCC1sggYZ9DQY0OdArrcwoj6BofBk",
  "uuid": "7231997808928032770",
  "cover": "https://p16-sg.tiktokcdn.com/aweme/100x100/tos-alisg-v-2774/oYHMADhIgAFdBaDftgrjLQoIsFZSsCeZEIpBAa.jpeg",
  "title": "Boundless Worship",
  "artist": "Josué Novais Piano Worship",
  "duration": 715,
  "selection": "trending_clip",
  "music_volume": 50,
  "original_sound_volume": 0
}

5.12 Publish a Post (POST /v1/publish/article)

Cross-platform publishing. Fields such as type, extra, and attachments are platform-specific; complete them according to the target platform.

The url and thumb in attachments must be file addresses recognized by the current SocialEcho OSS configuration. It is recommended to use only the public_url returned by GET /v1/upload/url. The server automatically parses attachment type, dimensions, size, duration, and frame rate from the OSS file; callers do not need to submit these metadata fields.

Example type values:

• Facebook: reels / post / stories.
• YouTube: shorts / video.
• Instagram: reels / post / stories.
• X: short_post / long_post.
• LinkedIn: post.
• TikTok: video / photo.
• TikTok Shop: video / photo.
• Pinterest: post.
• Reddit: text / link / media.
• Threads: post.
• Telegram: post.

5.12.1 Publishing Field Quick Reference by Platform

The following are the main validation rules for the current external publishing endpoint. File sizes are per-attachment limits. The server automatically parses and validates media dimensions, frame rate, duration, and aspect ratio from OSS.

YouTube extra.tags must be a string array: it must not contain empty values, duplicates, or control characters. After applying YouTube's comma and quotation mark counting rules, the total length must not exceed 500. A YouTube video cover is passed through attachments[0].thumb; only jpg, jpeg, and png are supported, with a maximum size of 2 MiB.

Instagram extra.collaborators must be an array of username strings and may include or omit the leading @. Usernames may contain only letters, numbers, periods, and underscores, and must not be duplicated. When Reddit does not need flair, omit extra.flair completely. When flair is provided, both uuid and title are required.

Generic request example (cURL)

curl --request POST 'https://api.socialecho.net/v1/publish/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --data @publish-payload.json

5.12.2 Publish TikTok Shop Shoppable Content

Before publishing, complete these steps in order:

1. Call /v1/account to obtain the ID of a TikTok Shop account in a normal state.
2. Call /v1/tiktokshop/products to obtain the product to attach.
3. Optionally call the music genres and trending music endpoints to select music.
4. Call /v1/upload/url and upload the video or images to OSS.
5. Submit the publishing request using the public_url from the upload response.

Video publish-payload.json example

{
  "account_id": 123456,
  "type": "video",
  "status": 1,
  "content": "A simple statement piece for every cozy corner. #HomeDecor #TikTokShop",
  "extra": {
    "title": "Minimalist Ceramic Vase",
    "product": {
      "id": 789,
      "uuid": "1732443576158556877",
      "title": "Ceramic Flower Vase",
      "thumb": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product.jpg"
    },
    "music": {
      "url": "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2102/oUNQD7eSEFCC1sggYZ9DQY0OdArrcwoj6BofBk",
      "uuid": "7231997808928032770",
      "cover": "https://p16-sg.tiktokcdn.com/aweme/100x100/tos-alisg-v-2774/oYHMADhIgAFdBaDftgrjLQoIsFZSsCeZEIpBAa.jpeg",
      "title": "Boundless Worship",
      "artist": "Josué Novais Piano Worship",
      "duration": 715,
      "selection": "trending_clip",
      "music_volume": 50,
      "original_sound_volume": 0
    }
  },
  "attachments": [{
    "url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product-video.mp4"
  }],
  "comment": []
}

The OSS addresses in the example above illustrate the field format. In actual requests, replace them with the public_url returned by the current upload request. Product fields must use the current values returned by the product list endpoint.

Photo publish-payload.json example

{
  "account_id": 123456,
  "type": "photo",
  "status": 1,
  "content": "A cozy update for your favorite corner. #HomeDecor #TikTokShop",
  "extra": {
    "title": "Minimalist Ceramic Vase",
    "product": {
      "id": 789,
      "uuid": "1732443576158556877",
      "title": "Ceramic Flower Vase",
      "thumb": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product.jpg"
    }
  },
  "attachments": [
    {"url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product-1.jpg"},
    {"url": "https://oss.socialecho.net/team/TEAM_ABC123/20260828/product-2.jpg"}
  ],
  "comment": []
}

General TikTok Shop field requirements:

• account_id must be a TikTok Shop account in a normal state and belonging to the current team.
• type supports only video or photo.
• extra.title is required, with a maximum of 30 characters. It supports only Unicode letters, numbers, and spaces; punctuation is not supported, although letters from languages such as Chinese are allowed.
• extra.product is required. id, uuid, title, and thumb must be taken directly from the product list endpoint.
• The product must be available, meaning that the product list returns status = 1.
• extra.music is optional. When music is selected, all nine fields must be provided: url, uuid, cover, title, artist, duration, selection, music_volume, and original_sound_volume.
• extra.music.url, uuid, cover, title, artist, and duration must use the original values from the current music query result. Do not construct, truncate, or reduce them to only the UUID.
• extra.music.selection supports none, trending_clip, and full_track. When it is not none, a complete music object is required.
• extra.music.music_volume and extra.music.original_sound_volume must be integers from 0 to 100; the example values are 50 and 0, respectively.
• When no music is selected, extra.music may be omitted or set to {"selection":"none"}. Do not pass only the UUID for selected music.
• status = 1 with no scheduled_at means submit for immediate publishing.

TikTok Shop video requirements:

• content is required and must not exceed 2,200 UTF-16 code units.
• Only one video attachment is supported; the video must not exceed 500 MB.
• Supported formats are mp4, mov, mkv, wmv, webm, avi, 3gp, flv, mpeg, and mpg. For files of 10 MiB or larger, use mp4, mov, or webm.
• extra.is_ai_generated is optional and must be a boolean.

TikTok Shop photo requirements:

• content is optional; when provided, it must not exceed 5,000 UTF-16 code units.
• attachments must contain at least one image and may contain images only. The current endpoint does not set an image count limit, but TikTok Shop platform limits still apply.
• Supported image formats are jpg, jpeg, png, webp, heic, and bmp; each image must be larger than 0 and no larger than 10 MiB.
• The dimensions of each image must be parseable, and its aspect ratio must be between 9:16 and 16:9.

Response example

{
  "code": 0,
  "message": "Submitted successfully",
  "data": {"id": 183308},
  "request_id": "018f7f35-7c9a-7b82-a0f2-6a06b0b7d301"
}

data.id in the response is the SocialEcho publishing record ID. HTTP 200 with business code = 0 means that the task was submitted successfully; it does not mean that TikTok Shop has completed final publishing. Platform publishing, video processing, and review are asynchronous.

TikTok Shop publishing endpoint statuses:

The publishing endpoint submits the asynchronous task only after creating the record. Therefore, when HTTP 422 or 500 is returned during submission, it is not guaranteed that no publishing record was created. Do not resubmit immediately. First save request_id, confirm through the post list or the backend record whether a corresponding publishing record was created, and then decide whether to retry to avoid duplicate publishing.

6. Integration Recommendations

1. Retrieve the account list first, then pass account_id to the post, report, resource query, and publishing endpoints to avoid using an account that does not belong to the current team.
2. For paginated endpoints, loop over page consistently and stop when the response satisfies meta.current_page >= meta.last_page.
3. In workflow platforms such as n8n, Zapier, and Dify, separate failure branches for authentication failures, parameter failures, rate-limit failures, and upstream platform failures.
4. Record the request time, endpoint name, HTTP status code, business code, request_id, and key request parameters for production troubleshooting.
5. Publishing endpoints should first call GET /v1/upload/url to upload assets, then build attachments.
6. TikTok Shop publishing should always use the complete product object returned by the product list endpoint; do not construct it manually or cache product status for a long time.
7. Trending music may change by country, category, and date range; query it in real time before publishing.
8. Keep all automated requests within 120 requests per minute for a single API Key, and configure exponential backoff for 429, 502, and network timeouts.

7. Frequently Asked Questions (FAQ)

Q1: How do I determine whether an API call succeeded?

A: It is successful only when the HTTP status code is 2xx and code = 0 in the JSON. All HTTP 4xx/5xx responses are failures, but the response body should still be parsed to obtain code, error, data, and request_id. If an HTTP 2xx response contains a non-zero code, treat it as a contract violation and record request_id.

Q2: How do I pass account_ids in the QueryString?

A: Repeat the parameter key with brackets, for example, account_ids[]=163956&account_ids[]=163955&account_ids[]=28.

Q3: How can I avoid triggering 429?

A: Keep a single API Key below 120 requests per minute and configure throttling and exponential backoff. Prefer waiting according to Retry-After. If the product synchronization cooldown does not return that header, wait according to data.next_allowed_at or the response message.

Q4: How do I confirm that an account is a TikTok Shop account?

A: Call /v1/account, check whether app.title in the returned item is TikTokShop, and confirm that status.value = 1.

Q5: What should I do if a product keyword search returns no results?

A: Some product titles are in English. Use an English keyword, or omit keyword to retrieve all products and filter them afterward.

Q6: Why is the new video not immediately visible on the TikTok profile after the publishing endpoint succeeds?

A: Publishing endpoint success only means that the task was submitted. Video upload, TikTok Shop publishing, and platform review are asynchronous and may take time. Keep the publishing record ID and request_id from the response for troubleshooting.

Q7: What is the difference between upload_url and public_url in the upload response?

A: upload_url is a time-limited OSS presigned upload URL used only to upload the file. public_url is the file address that the publishing endpoint should use as attachments[].url.

Q8: Why does the music endpoint not return volume fields?

A: The trending music endpoint returns six music asset fields: url, uuid, cover, title, artist, and duration. After selecting music, the caller must copy these six original values into extra.music and add the three publishing control fields selection, music_volume, and original_sound_volume, for a total of nine fields. When a TikTok Shop video plays only the selected music, you can use music_volume = 50 and original_sound_volume = 0.

Q9: Should I pass id or uuid when publishing to a Pinterest board or Reddit community?

A: extra.category_id must be the integer data[].id returned by the list endpoint. uuid is the platform resource identifier, not the category_id for the publishing endpoint. Reddit flair is the exception: when flair is required, pass extra.flair.uuid and extra.flair.title separately.

Q10: Is passing only url in a publishing attachment sufficient?

A: Yes. Each item in attachments[] needs at least the public_url from the current OSS upload response. For a custom video cover, you can also pass thumb. The server reads OSS metadata and fills in attachment type, size, dimensions, duration, and frame rate. External CDN URLs, upload_url, expired signed URLs, or addresses outside SocialEcho OSS fail validation.

This document corresponds to SocialEcho OpenAPI v1 and was revised on 2026-08-28. Integrators should assemble requests according to the fields and examples in this document and recheck platform publishing limits when upgrading the documentation version.