# 社群媒體發布 API

> 綁定社群媒體帳號、排程貼文，並將 AI 生成短片發布到 YouTube、TikTok、Instagram、Facebook、X / Twitter、LinkedIn 等平台。

## 社群媒體發布 API

社群媒體發布 API 可讓你綁定社群媒體帳號，並將 WayinVideo 短片直接發布到這些帳號。

此 API 適用於 [AI 剪輯](https://wayin.ai/zh-tw/api-docs/ai-clipping/) 和 [時刻搜尋](https://wayin.ai/zh-tw/api-docs/find-moments/) 產生的已匯出短片。請先使用其中一個 API 建立短片，並確保原始任務提交時已設定 `enable_export = true`。之後再使用取得的 `project_id` 和短片 `idx` 建立發布任務。

典型流程：

1. 為目標平台建立 OAuth 授權 URL。
2. 在瀏覽器中開啟回傳的 `auth_url` 並完成授權。
3. 呼叫帳號列表接口，確認已綁定帳號並取得帳號 `id`。
4. 使用目標短片與平台發布設定建立發布任務。

所有接口都需要：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
x-wayinvideo-api-version: v2
```

> **計費：** 限時促銷期間，每成功綁定 1 個社群媒體帳號目前消耗 **10 API Units**。如果授權未成功完成，不會扣除 API Units。

---

## 接口概覽

| 方法   | 路徑                                    | 說明                                   |
| ------ | --------------------------------------- | -------------------------------------- |
| `POST` | `/api/v2/social-media/oauth/{platform}` | 建立一次性的社群媒體 OAuth 授權 URL   |
| `GET`  | `/api/v2/social-media/accounts`         | 取得已綁定的社群媒體帳號列表          |
| `POST` | `/api/v2/social-media/publish`          | 建立短片發布任務，可發布到一個或多個帳號 |

---

## 綁定社群媒體帳號

為要綁定的平台建立 OAuth 授權 URL。

```
POST https://wayinvideo-api.wayin.ai/api/v2/social-media/oauth/{platform}
```

### 路徑參數

| 參數       | 類型   | 必填 | 說明                                                                                      |
| ---------- | ------ | ---- | ----------------------------------------------------------------------------------------- |
| `platform` | string | 是   | 社群媒體平台。可用值：`youtube`、`tiktok`、`twitter`、`instagram`、`facebook`、`linkedin`。 |

### 請求體

不需要請求體。

### 請求示例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/social-media/oauth/youtube \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-wayinvideo-api-version: v2" \
  --data ''
```

### 回應示例

```json
{
  "data": {
    "auth_url": "https://example.com/oauth2/auth?xxxxxx",
    "state": "a49bc736-xxxxx"
  }
}
```

### 回應欄位

| 欄位       | 類型   | 說明                                             |
| ---------- | ------ | ------------------------------------------------ |
| `auth_url` | string | 第三方 OAuth 授權頁面 URL。請在瀏覽器中開啟完成授權。 |
| `state`    | string | 授權狀態識別值。                                 |

### 注意

- 每個 `auth_url` 只能使用一次。若授權失敗或 URL 過期，請重新呼叫此接口取得新的 URL。
- 授權成功後，呼叫[取得社群媒體帳號](#取得社群媒體帳號)確認帳號可用。
- 同一平台可以綁定多個帳號。例如多次呼叫 YouTube OAuth 接口即可綁定多個 YouTube 頻道。
- 如果帳號未成功綁定，不會扣除 API Units。

---

## 取得社群媒體帳號

取得目前 API Key 所屬使用者已綁定的社群媒體帳號。發布前可透過此接口取得 `publish_configs` 需要使用的帳號 `id`。

```
GET https://wayinvideo-api.wayin.ai/api/v2/social-media/accounts?active_only={active_only}
```

### 查詢參數

| 參數          | 類型    | 必填 | 預設值  | 說明                               |
| ------------- | ------- | ---- | ------- | ---------------------------------- |
| `active_only` | boolean | 否   | `false` | 為 `true` 時，只回傳 token 有效的帳號。 |

### 請求示例

```bash
curl -X GET "https://wayinvideo-api.wayin.ai/api/v2/social-media/accounts?active_only=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-wayinvideo-api-version: v2"
```

### 未綁定帳號時的回應

```json
{
  "data": []
}
```

如果 `data` 為空，請先呼叫[綁定社群媒體帳號](#綁定社群媒體帳號)。

### 已綁定帳號時的回應

```json
{
  "data": [
    {
      "id": "smaccxxx",
      "platform": "youtube",
      "platform_username": "MyChannel",
      "platform_avatar": "https://example.com/avatar.jpg",
      "token_valid": true,
      "token_expiring_soon": false
    }
  ]
}
```

### 回應欄位

| 欄位                  | 類型           | 說明                                                                 |
| --------------------- | -------------- | -------------------------------------------------------------------- |
| `id`                  | string         | 社群帳號唯一 ID。呼叫 `/publish` 時必須用作 `publish_configs` 的 key。 |
| `platform`            | string         | 平台識別值。見[平台值](#平台值)。                                    |
| `platform_username`   | string         | 該平台上的使用者名稱、頻道名稱或帳號名稱。                           |
| `platform_avatar`     | string \| null | 帳號頭像 URL。                                                       |
| `token_valid`         | boolean        | `true` 表示授權 token 有效，可用於發布。                             |
| `token_expiring_soon` | boolean        | `true` 表示 token 即將過期，建議重新授權。                           |

### 使用建議

- 建立發布任務前，請確認目標帳號的 `token_valid` 為 `true`。

---

## 建立發布任務

將一個短片發布到一個或多個已綁定的社群媒體帳號。透過專案 ID 和短片索引定位短片。

> **必要條件：** `project_id` 必須來自提交時設定了 `enable_export = true` 的 AI 剪輯或時刻搜尋任務。社群發布需要已匯出的短片影片；未啟用匯出的專案無法使用此接口發布。

```
POST https://wayinvideo-api.wayin.ai/api/v2/social-media/publish
```

### 請求欄位

| 欄位              | 類型            | 必填 | 說明                                                      |
| ----------------- | --------------- | ---- | --------------------------------------------------------- |
| `project_id`      | string          | 是   | 專案 ID。                                                 |
| `idx`             | integer         | 是   | 專案中的短片索引。                                        |
| `resolution`      | string          | 否   | 已匯出短片使用的解析度，例如 `1080p` 或 `720p`。          |
| `publish_configs` | object          | 是   | 發布設定，key 為社群帳號 ID。                             |
| `scheduled_at`    | integer \| null | 否   | 定時發布時間戳（毫秒）。傳 `null` 或省略表示立即發布。     |

> **如何生成 `scheduled_at` 值**
>
> `scheduled_at` 是毫秒級 Unix 時間戳，必須至少是 5 分鐘後，且不能超過 30 天後。
>
> JavaScript 中生成 10 分鐘後的時間：
>
> ```js
> const scheduledAt = Date.now() + 10 * 60 * 1000;
> ```
>
> 指定某個具體時間：
>
> ```js
> const scheduledAt = new Date('2026-06-15T10:00:00Z').getTime();
> ```

### 平台發布設定

`publish_configs` 的每個 value 都是平台相關的發布設定物件。

| 欄位               | 類型     | 必填     | 說明                                  |
| ------------------ | -------- | -------- | ------------------------------------- |
| `title`            | string   | 條件必填 | 影片標題。YouTube 必填。              |
| `description`      | string   | 條件必填 | 影片描述或正文。TikTok 必填。         |
| `tags`             | string[] | 否       | 標籤列表。                            |
| `visibility`       | string   | 否       | 可見性：`public`、`private`、`unlisted`。不同平台支援情況不同。 |
| `thumbnail_url`    | string   | 否       | 自訂封面圖 URL。                      |
| `category`         | string   | 否       | 平台相關的影片分類。                  |
| `allow_comment`    | boolean  | 否       | 是否允許評論。                        |
| `allow_duet`       | boolean  | 否       | 是否允許合拍，僅 TikTok。             |
| `allow_stitch`     | boolean  | 否       | 是否允許拼接，僅 TikTok。             |
| `disclose_content` | boolean  | 否       | 是否披露推廣或廣告內容，僅 TikTok。   |

> **重要：** `publish_configs` 的 key 必須是 `/api/v2/social-media/accounts` 回傳的帳號 ID，例如 `smacct06ixxxxxxx`。不要使用 `youtube`、`tiktok` 等平台名稱作為 key。

### 請求示例

```bash
curl -sS -X POST https://wayinvideo-api.wayin.ai/api/v2/social-media/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "project_id": "prj06ixxxxxxx",
    "idx": 0,
    "resolution": "1080p",
    "publish_configs": {
      "smacct06ixxxxxxx": {
        "title": "API Test Video",
        "description": "Posted by curl test",
        "tags": ["api", "test"],
        "visibility": "public"
      }
    },
    "scheduled_at": null
  }'
```

### 回應示例

```json
{
  "data": {
    "task_id": "pubtask06ixxxxxxx",
    "status": "PENDING",
    "created_at": 1781251687210
  }
}
```

你可以在 [WayinVideo calendar](https://wayin.ai/wayinvideo/calendar) 查看發布排程與即時任務結果。

---

## 平台值

| 值          | 平台        | 網站                  |
| ----------- | ----------- | --------------------- |
| `youtube`   | YouTube     | https://youtube.com   |
| `tiktok`    | TikTok      | https://tiktok.com    |
| `twitter`   | Twitter / X | https://twitter.com   |
| `instagram` | Instagram   | https://instagram.com |
| `facebook`  | Facebook    | https://facebook.com  |
| `linkedin`  | LinkedIn    | https://linkedin.com  |

## 發布狀態值

| 值             | 說明                               |
| -------------- | ---------------------------------- |
| `PENDING`      | 任務已建立，等待排程。             |
| `SCHEDULED`    | 已排程，等待觸發。                 |
| `PROCESSING`   | 發布進行中，包括影片上傳與平台處理。 |
| `DONE`         | 發布成功。                         |
| `PARTIAL_DONE` | 部分成功，僅多帳號發布時可能出現。 |
| `ERROR`        | 發布失敗。                         |
| `CANCELLED`    | 已取消。                           |

---

## 完整流程示例

1. 呼叫 OAuth 接口並在瀏覽器開啟 `auth_url` 完成授權。
2. 呼叫帳號列表接口，複製目標帳號的 `id`。
3. 使用 `project_id`、`idx` 和 `publish_configs` 建立發布任務。

---

## 注意事項

1. `publish_configs` 的 key 是已綁定帳號 ID，不是平台名稱。
2. 定時發布請傳入未來毫秒時間戳；`null` 或省略表示立即發布。
3. 定時發布時間必須至少為 5 分鐘後，且不超過 30 天後。
4. 社群發布需要已匯出的短片影片。請使用 `enable_export = true` 建立的 AI 剪輯或時刻搜尋任務的 `project_id`。
5. 如果發布時回傳帳號 token 錯誤，請重新綁定該社群媒體帳號後再試。
6. 同一短片可以多次發布；同一帳號重複發布同一短片會建立獨立任務。