> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok API

> 使用 TikTok API 發布內容的選項

<Info>
  Ayrshare 透過 TikTok API 為個人或商業 TikTok 帳號提供 [TikTok 影片直接發布](https://www.ayrshare.com/blog/introducing-tiktok-direct-publishing-analytics-and-commenting/)、留言管理與進階分析取得等功能。

  TikTok 會以非同步方式處理影片與圖片，因此不論是立即發布或排程發布，JSON 回應的 status 都會是 "pending"。TikTok 處理完成後，會呼叫你註冊的 [Scheduled Action webhook](/apis/webhooks/actions#scheduled-action)。
</Info>

## TikTok 影片貼文

直接發布的基本 TikTok 影片貼文 JSON 範例：

```json TikTok Video Post theme={"system"}
{
  "post": "The best TikTok \n video ever #bestvideo", // Max 2,200 characters with a line break
  "mediaUrls": ["https://img.ayrshare.com/012/tiktok.mp4"],
  "platforms": ["tiktok"]
}
```

JSON 發布回應範例：

```json TikTok Video Post Response theme={"system"}
{
  "status": "success",
  "errors": [],
  "postIds": [
    {
      "status": "success",
      "idShare": "video.7088122496758679353.nzLqBWbf",
      "id": "pending",
      "isVideo": true,
      "platform": "tiktok"
    }
  ],
  "id": "lb42orDhySAZmLWtj6b6",
  "refId": "23a9da9e0df1184a7a6a1fc2c60b8023aa9a32a1",
  "post": "The best TikTok video ever #bestvideo"
}
```

<ul class="custom-bullets">
  <li>
    TikTok 目前不支援貼文文字中的換行。所包含的換行會被忽略。
  </li>

  <li>
    每則貼文可發布一部影片或最多 35 張圖片。TikTok 不支援
    影片與圖片混合發布。詳情請參閱下方說明。
  </li>

  <li>
    如果影片的副檔名不是常見的影片格式，請使用
    [isVideo](/apis/post/overview#video-extension)。
  </li>

  <li>
    TikTok 也支援發送不含貼文文字的媒體。如果你不想包含貼文文字，
    請傳送空字串 `post: ""`。
  </li>

  <li>
    更多資訊請參閱 [TikTok 媒體指南](/media-guidelines/tiktok) 與 [TikTok
    授權](/dashboard/connect-social-accounts/tiktok)。
  </li>
</ul>

### TikTok 影片需求

<ul class="custom-bullets">
  <li>請參閱 [TikTok 影片需求](/media-guidelines/tiktok#video)。</li>

  <li>
    影片必須以已知的影片副檔名（例如 mp4）結尾。你可以對該 URL 設置反向代理、
    使用 [CDN 建立 vanity URL](https://www.ayrshare.com/blog/how-to-put-a-cdn-in-front-of-firebase-cloud-storage/)，或使用
    [/media](/apis/media/overview) 端點。
  </li>

  <li>TikTok 貼文文字的字元上限為 2,200。</li>
</ul>

<Note>
  TikTok 將 API 影片發布限制為每分鐘 6 部影片，且每日上限為 15 部影片。
</Note>

## TikTok 圖片貼文

直接發布的基本 TikTok 圖片（照片）貼文 JSON 範例：

```json TikTok Image Post theme={"system"}
{
  "post": "The best TikTok \n video ever #bestvideo", // Max 2,200 characters with a line break
  "mediaUrls": [
    "https://img.ayrshare.com/012/gb.jpg",
    "https://img.ayrshare.com/random/photo-1.jpg"
  ], // Up to 35 images
  "platforms": ["tiktok"]
}
```

JSON 回應範例：

```json TikTok Image Post Response theme={"system"}
{
  "status": "success",
  "errors": [],
  "postIds": [
    {
      "status": "success",
      "idShare": "p_pub_url~v2.7408974036430047275",
      "id": "pending",
      "isVideo": false,
      "platform": "tiktok"
    }
  ],
  "id": "8815mJ5bWApEebWjE233",
  "tikTokId": "p_pub_url~v2.7408974036430047333",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc333",
  "post": "Opportunity is missed by most people because it is dressed in overalls and looks like work - Thomas Edison"
}
```

<ul class="custom-bullets">
  <li>
    TikTok 目前不支援貼文文字中的換行。所包含的換行會被忽略。
  </li>

  <li>每則貼文可發布一部影片或最多 35 張圖片。</li>

  <li>
    TikTok 不支援影片與圖片混合發布。詳情請參閱下方說明。
  </li>

  <li>圖片必須為 JPG、JPEG 或 WEBP 格式。TikTok 不接受 PNG 媒體檔案。</li>

  <li>
    你也可以透過 `imageCoverIndex` 選擇其中一張圖片作為封面。預設情況下
    會使用第一張圖片。詳情請參閱下方說明。
  </li>
</ul>

### TikTok 圖片需求

<ul class="custom-bullets">
  <li>請參閱 [TikTok 圖片需求](/media-guidelines/tiktok#images)。</li>
  <li>單則貼文最多可包含 35 張圖片，每張最大 20 MB。</li>
  <li>圖片必須為 JPG、JPEG 或 WEBP 格式。TikTok 不接受 PNG 媒體檔案。</li>
  <li>TikTok 貼文文字的字元上限為 2,200。</li>
</ul>

<Note>
  TikTok 將 API 圖片發布限制為每分鐘 6 張照片，且每日上限為 15 張照片。
</Note>

## TikTok 處理

TikTok 以非同步方式處理影片與圖片，因此回應中的 `id` 欄位會被設為 `"pending"`。
TikTok 處理完成（通常在 1 - 2 分鐘內）後，`id` 欄位會被更新為 TikTok 影片 `id`，並會新增 `postUrl`。

<ul class="custom-bullets">
  <li>
    你可以使用 [webhooks](/apis/webhooks/actions#tiktok-publishing-webhook) 或
    [/history](/apis/history/overview) 端點取得 TikTok 貼文的最終狀態，通常需要 1-2 分鐘才會可用。
  </li>

  <li>
    當使用者在 TikTok 行動 App 中發布影片時，會發送一個 "scheduled" webhook，
    其 `subAction: "tikTokPublished"`。
  </li>

  <li>
    TikTok 貼文的 [首則留言](/apis/post/overview#first-comment) 會延後發布：
    留言會在 `tikTokPublished` webhook 解析出真正的影片 `id` 後才自動發布，
    而非在發布時發布。影片的 `visibility` 必須為 `public`，否則首則留言無法發布，並會回傳
    留言錯誤。
  </li>

  <li>
    如果發生錯誤（例如 TikTok 無法處理該影片，或 Ayrshare 內部檢查失敗），
    `id` 欄位會被設為 "failed"，`errors` 欄位則會包含錯誤
    細節。
  </li>

  <li>`idShare` 用於內部參照該待處理的影片。</li>
</ul>

## TikTok 選項

在發布 TikTok 影片或圖片時，還有 [其他可用選項](/apis/post/social-networks/tiktok#available-tiktok-options)。

影片發布範例：

```json TikTok Video Publishing theme={"system"}
{
  "tikTokOptions": {
    "disableComments": true, // Default false. Disable comments on the published video.
    "disableDuet": true, // Default false. Disable duets on the published video.
    "disableStitch": true // Default false. Disable stitches on the published video.
  }
}
```

圖片發布範例：

```json TikTok Image Publishing theme={"system"}
{
  "tikTokOptions": {
    "imageCoverIndex": 1, // Use the second image in the mediaUrls.
    "title": "Amazing images"
  }
}
```

### 選項

以下選項適用於 TikTok 貼文。
請將這些選項加到 `tikTokOptions` 物件中。
各選項的詳細說明請參閱下方。

```json TikTok Options theme={"system"}
{
  "post": "The best TikTok video ever #bestvideo",
  "mediaUrls": ["https://img.ayrshare.com/012/tiktok.mp4"],
  "platforms": ["tiktok"],
  "tikTokOptions": {
    "autoAddMusic": true,
    "disableComments": true,
    "disableDuet": true,
    "disableStitch": true,
    "draft": true,
    "isAIGenerated": true,
    "isBrandedContent": true,
    "isBrandOrganic": true,
    "imageCoverIndex": 1,
    "title": "Amazing images",
    "thumbNailOffset": 30000,
    "visibility": "public"
  }
}
```

<ParamField body="autoAddMusic" type="boolean" default={false}>
  是否自動為貼文加入推薦音樂。
  若將此欄位設為 `true`，你之後可以在 TikTok App 中變更音樂。

  適用媒體類型：image
</ParamField>

<ParamField body="disableComments" type="boolean" default={false}>
  是否停用已發布貼文的留言功能。

  適用媒體類型：video、image
</ParamField>

<ParamField body="disableDuet" type="boolean" default={false}>
  停用已發布影片的合拍（duet）功能。

  適用媒體類型：video
</ParamField>

<ParamField body="disableStitch" type="boolean" default={false}>
  停用已發布影片的搶鏡（stitch）功能。

  適用媒體類型：video
</ParamField>

<ParamField body="draft" type="boolean" default={false}>
  是否建立草稿貼文。

  更多資訊請參閱 [草稿選項](/apis/post/social-networks/tiktok#tiktok-video-draft-post)。

  適用媒體類型：video 或 image
</ParamField>

<ParamField body="isAIGenerated" type="boolean" default={false}>
  是否為影片貼文啟用 AI 生成內容標示。

  若啟用此標示，你的影片一旦發布後就會被標為「Creator labeled as AI-generated」且無法變更。
  「Creator labeled as AI-generated」標示表示該內容完全由 AI 生成或經 AI 大幅編輯。

  <Note>
    只要不違反 TikTok 的 [社群
    規範](https://www.tiktok.com/community-guidelines/en/)，開啟 AI 生成內容設定不會影響
    影片的散布。
  </Note>

  適用媒體類型：video
</ParamField>

<ParamField body="isBrandedContent" type="boolean" default={false}>
  是否啟用 <a href="https://creatormarketplace.tiktok.com/help#/doc/9493/10008169">Branded Content</a> 標示。若此欄位設為 `true`，該影片會被標為 Branded Content，表示你與某品牌有付費合作關係，影片上會加上「Paid partnership」標示。

  適用媒體類型：video、image
</ParamField>

<ParamField body="isBrandOrganic" type="boolean" default={false}>
  是否啟用 Brand Organic Content 標示。若此欄位設為 `true`，該影片會被標為 Brand Organic Content，表示你正在推廣自己或自身的商業，影片上會加上「Promotional content」標示。

  適用媒體類型：video、image
</ParamField>

<ParamField body="imageCoverIndex" type="number" default="0">
  `mediaUrls` 中要用作貼文封面的索引。

  適用媒體類型：image
</ParamField>

<ParamField body="title" type="string">
  貼文標題。

  適用媒體類型：image
</ParamField>

<ParamField body="thumbNailOffset" type="number">
  用於影片封面的影格。

  更多資訊請參閱 [影片縮圖選項](/apis/post/social-networks/tiktok#video-thumbnail)。

  適用媒體類型：video
</ParamField>

<ParamField body="visibility" type="string" default="public">
  貼文的分享方式，以及誰可以看到。

  可用的值：`public`、`private`、`followers` 或 `friends`。

  更多資訊請參閱 [可見性選項](/apis/post/social-networks/tiktok#visibility-options)。

  適用媒體類型：image
</ParamField>

### 可見性選項

| 可見性       | 說明                |
| :-------- | :---------------- |
| public    | 所有 TikTok 使用者皆可見。 |
| private   | 私人，只有帳號本身可見。      |
| followers | 只有帳號的追蹤者可見。       |
| friends   | 只有互相追蹤的使用者可見。     |

私人貼文會維持在 `pending` 狀態，且在貼文轉為公開之前不會發送 TikTok webhook。

## 影片縮圖

為 TikTok 影片設定縮圖（也稱為封面圖片）有兩種方式：

1. 使用 `thumbNailOffset` 參數設定縮圖影格。
2. 使用 `thumbNail` 參數以 URL 設定縮圖圖片。

僅影片支援設定縮圖。

### 縮圖 Offset

透過選擇 offset 影格為 TikTok 影片設定縮圖。

```json TikTok Video Thumbnail Offset theme={"system"}
{
  "tikTokOptions": {
    "thumbNailOffset": 30000 // milliseconds of offset image
  }
}
```

Offset 是縮圖影格在影片中的位置（毫秒）。預設值為 `0`，即影片的第一格。

### 縮圖 URL

透過從 URL 上傳圖片為 TikTok 影片設定縮圖。

```json TikTok Video Thumbnail URL theme={"system"}
{
  "tikTokOptions": {
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

若使用 `thumbNail` 參數，`thumbNailOffset` 參數會被忽略。

更多資訊請參閱 [TikTok 縮圖需求](/media-guidelines/tiktok#video-thumbnail)。

## TikTok 提及

在貼文文字中加入 `@handle` 即可提及其他 TikTok 使用者。例如：

```json TikTok Mention theme={"system"}
{
  "post": "Love the @ayrshare social media api"
}
```

<Warning>
  請詳閱關於提及功能的[重要規則](/testing/post-verification#mentions)。
</Warning>

## TikTok 草稿貼文

為 TikTok 影片或圖片建立草稿貼文，讓你可以在發布前先編輯影片或圖片。

```json TikTok Video Draft Post theme={"system"}
{
  "post": "The best TikTok video ever #bestvideo", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/tiktok.mp4"],
  "platforms": ["tiktok"],
  "tikTokOptions": {
    "draft": true
  }
}
```

草稿的影片或圖片貼文可以在 TikTok App 底部通知 **Inbox** 中找到。
請尋找 **System notifications** 訊息，然後點擊最上方的 **Your content from Ayrshare is ready** 訊息。

在影片發布前，Ayrshare `postUrl` 會維持在 `pending` 狀態。草稿貼文不支援首則留言。

<img src="https://mintcdn.com/ayrshare-docs/Nmrhj2Gh7WSf62Bh/images/apis/post/tiktok-draft-post.webp?fit=max&auto=format&n=Nmrhj2Gh7WSf62Bh&q=85&s=6e7fdce5ef106f6af6cd060bfbc446ba" alt="TikTok Draft Post" class="center" width="278" height="600" data-path="images/apis/post/tiktok-draft-post.webp" />

## 授權重新整理

TikTok 必須「每年」透過 Social Accounts 頁面重新授權一次。

<ul class="custom-bullets">
  <li>
    授權到期前 15 天，會發送電子郵件與 webhook social action 通知。
  </li>

  <li>
    你可以從 [/user](/apis/user/overview) 端點取得授權到期日與
    剩餘天數。
  </li>
</ul>

## 字元限制

更多資訊請參閱 [TikTok 字元限制](/help-center/technical-support/character_limits#tiktok-character-limits)。

## 補充資訊

更多 [使用 TikTok API 的範例](https://www.ayrshare.com/blog/tiktok-api-how-to-post-to-tiktok-using-a-social-media-api/)。