# Social Media Publishing API

> Connect social media accounts, schedule posts, and publish AI-generated clips to YouTube, TikTok, Instagram, Facebook, X / Twitter, LinkedIn, and more.

## Social Media Publishing API

Use the Social Media Publishing API to connect social media accounts, schedule posts, and publish WayinVideo clips directly to supported platforms including YouTube, TikTok, Instagram, Facebook, X / Twitter, and LinkedIn.

This API is designed for exported clips generated by [AI Clipping](https://wayin.ai/api-docs/ai-clipping/) and [Find Moments](https://wayin.ai/api-docs/find-moments/). Create clips with either API first, make sure the original project was submitted with `enable_export = true`, and then use the resulting `project_id` and clip `idx` when creating a publishing task.

It is useful for apps and automations that need to move from long-form video to short-form distribution without manually downloading and re-uploading every clip. Common use cases include YouTube Shorts upload workflows, TikTok publishing pipelines, Instagram Reels distribution, social scheduling tools, and creator content dashboards.

Typical flow:

1. Create an OAuth authorization URL for the platform you want to connect.
2. Open the returned `auth_url` in a browser and complete authorization.
3. Call the accounts endpoint to confirm the connected account and copy its `id`.
4. Create a publishing task with the target clip and account-specific publish settings.

All endpoints require:

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

> **Billing:** Successfully connecting one social media account currently costs **10 API Units** during the limited-time promotional period. If authorization is not completed successfully, no API Units are deducted.

---

## What This API Is Best For

- Publishing AI-generated clips from long videos to one or more connected social accounts.
- Building a YouTube Shorts, TikTok, or Instagram Reels publishing workflow after clip generation.
- You can connect social accounts with OAuth instead of sharing platform credentials.
- Scheduling clip posts up to 30 days in advance.
- Powering creator dashboards, social media automation tools, CMS integrations, and internal editorial queues.

For the full creation-to-publishing workflow, start with [AI Clipping](https://wayin.ai/api-docs/ai-clipping/) or [Find Moments](https://wayin.ai/api-docs/find-moments/), enable clip export, then publish the generated clip with this API.

---

## Endpoints

| Method | Path                                    | Description                                                           |
| ------ | --------------------------------------- | --------------------------------------------------------------------- |
| `POST` | `/api/v2/social-media/oauth/{platform}` | Create a one-time OAuth authorization URL for a social media platform |
| `GET`  | `/api/v2/social-media/accounts`         | List connected social media accounts                                  |
| `POST` | `/api/v2/social-media/publish`          | Create a task to publish a clip to one or more connected accounts     |

---

## Connect a Social Media Account

Create an OAuth authorization URL for the platform you want to connect.

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

### Path Parameters

| Parameter  | Type   | Required | Description                                                                                                 |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `platform` | string | Yes      | Social media platform. Allowed values: `youtube`, `tiktok`, `twitter`, `instagram`, `facebook`, `linkedin`. |

### Request Body

No request body is required.

### Example Request

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

### Example Response

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

### Response Fields

| Field      | Type   | Description                                                                                        |
| ---------- | ------ | -------------------------------------------------------------------------------------------------- |
| `auth_url` | string | The third-party OAuth authorization page URL. Open this URL in a browser to authorize the account. |
| `state`    | string | Authorization state identifier.                                                                    |

### Notes

- Each `auth_url` can be used only once. If authorization fails or the URL expires, call this endpoint again to create a new URL.
- After authorization succeeds, call [List Social Media Accounts](#list-social-media-accounts) to confirm that the account is available for publishing.
- You can connect multiple accounts on the same platform. For example, call the YouTube OAuth endpoint multiple times to connect multiple YouTube channels.
- If the account is not connected successfully, no API Units are deducted.

---

## List Social Media Accounts

Get all connected social media accounts for the current API key owner. Use this endpoint before publishing to find the account `id` values used by `publish_configs`.

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

### Query Parameters

| Parameter     | Type    | Required | Default | Description                                                |
| ------------- | ------- | -------- | ------- | ---------------------------------------------------------- |
| `active_only` | boolean | No       | `false` | When `true`, only accounts with valid tokens are returned. |

### Example Request

```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"
```

### Response When No Account Is Connected

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

If `data` is empty, call [Connect a Social Media Account](#connect-a-social-media-account) first.

### Response When Accounts Are Connected

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

### Response Fields

| Field                 | Type           | Description                                                                                                                          |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                  | string         | Unique social account ID. Use this as the key in `publish_configs` when calling `/publish`. Do not use the platform name as the key. |
| `platform`            | string         | Platform identifier. See [Platform values](#platform-values).                                                                        |
| `platform_username`   | string         | Username, channel name, or account name on the platform.                                                                             |
| `platform_avatar`     | string \| null | Avatar image URL for the account.                                                                                                    |
| `token_valid`         | boolean        | `true` means the authorization token is valid and the account can be used for publishing.                                            |
| `token_expiring_soon` | boolean        | `true` means the authorization token will expire soon. Reconnect the account before publishing again.                                |

### Recommended Usage

- Before creating a publish task, confirm that the target account has `token_valid: true`.

---

## Create a Publishing Task

Publish one clip to one or more connected social media accounts. Identify the clip by passing the project ID and clip index.

> **Required:** The `project_id` must come from an AI Clipping or Find Moments task submitted with `enable_export = true`. Social publishing requires an exported clip video; projects created without export enabled cannot be published with this endpoint.

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

### Request Fields

| Field             | Type            | Required               | Description                                                                                           |
| ----------------- | --------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `project_id`      | string          | Yes                    | Project ID.                                                                                           |
| `idx`             | integer         | Yes                    | Clip index within the project.                                                                        |
| `resolution`      | string          | No                     | Export resolution used by the exported clip, such as `1080p` or `720p`.                               |
| `publish_configs` | object          | Yes                    | Publish settings keyed by social account ID from the accounts endpoint.                               |
| `scheduled_at`    | integer \| null | No                     | Millisecond timestamp for scheduled publishing. Use `null` or omit this field to publish immediately. |

> **How to generate a `scheduled_at` value**
>
> `scheduled_at` is a Unix timestamp in milliseconds. It must be at least 5 minutes in the future and no more than 30 days in the future.
>
> To schedule publishing 10 minutes from now in JavaScript:
>
> ```js
> const scheduledAt = Date.now() + 10 * 60 * 1000;
> ```
>
> To schedule for a specific time:
>
> ```js
> const scheduledAt = new Date('2026-06-15T10:00:00Z').getTime();
> ```

### Platform Publish Config

Each value in `publish_configs` is a platform-specific publish config object.

| Field              | Type     | Required               | Description                                                              |
| ------------------ | -------- | ---------------------- | ------------------------------------------------------------------------ |
| `title`            | string   | Conditionally required | Video title. Required for YouTube.                                       |
| `description`      | string   | Conditionally required | Video description or post text. Required for TikTok.                     |
| `tags`             | string[] | No                     | Tag list.                                                                |
| `visibility`       | string   | No                     | Visibility: `public`, `private`, or `unlisted`. Platform support varies. |
| `thumbnail_url`    | string   | No                     | Custom thumbnail image URL.                                              |
| `category`         | string   | No                     | Platform-specific video category.                                        |
| `allow_comment`    | boolean  | No                     | Whether comments are allowed.                                            |
| `allow_duet`       | boolean  | No                     | Whether duets are allowed. TikTok only.                                  |
| `allow_stitch`     | boolean  | No                     | Whether stitches are allowed. TikTok only.                               |
| `disclose_content` | boolean  | No                     | Whether to disclose promotional or advertising content. TikTok only.     |

> **Important:** The keys inside `publish_configs` must be account IDs returned by `/api/v2/social-media/accounts`, such as `smacct06ixxxxxxx`. Do not use `youtube`, `tiktok`, or other platform names as keys.

### Example Request

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

### Example Response

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

### Response Fields

| Field          | Type            | Description                                                                  |
| -------------- | --------------- | ---------------------------------------------------------------------------- |
| `task_id`      | string          | Unique publishing task ID.                                                   |
| `status`       | string          | Publishing task status. See [Publish status values](#publish-status-values). |
| `created_at`   | integer         | Task creation timestamp in milliseconds.                                     |
| `schedule_id`  | string \| null  | Schedule ID. Returned when `scheduled_at` is provided.                       |
| `scheduled_at` | integer \| null | Scheduled publish timestamp in milliseconds.                                 |

You can view publishing schedules and live task results on the [WayinVideo calendar](https://wayin.ai/wayinvideo/calendar).

---

## Platform Values

| Value       | Platform    | Website               |
| ----------- | ----------- | --------------------- |
| `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  |

## Publish Status Values

| Value          | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `PENDING`      | The task has been created and is waiting to be scheduled.                                    |
| `SCHEDULED`    | The task has been scheduled and is waiting for the scheduled time.                           |
| `PROCESSING`   | Publishing is in progress, including video upload and platform-side processing.              |
| `DONE`         | Publishing succeeded.                                                                        |
| `PARTIAL_DONE` | Some accounts succeeded and some failed. Only possible when publishing to multiple accounts. |
| `ERROR`        | Publishing failed.                                                                           |
| `CANCELLED`    | Publishing was cancelled.                                                                    |

---

## Complete Flow Example

### Step 1: Create a YouTube OAuth URL

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

Open the returned `auth_url` in a browser and complete authorization.

### Step 2: List Available Accounts

```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"
```

Copy the `id` of the account you want to publish to.

### Step 3: Publish a Clip

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

---

## Notes

1. The `publish_configs` key is the connected account ID, not the platform name.
2. To schedule publishing, pass a future millisecond timestamp in `scheduled_at`. Use `null` or omit the field for immediate publishing.
3. Scheduled publishing must be at least 5 minutes in the future and no more than 30 days in the future.
4. Social publishing requires an exported clip video. Use a `project_id` from an AI Clipping or Find Moments task created with `enable_export = true`.
5. If publishing returns an account token error, reconnect the social media account and try again.
6. The same clip can be published multiple times. Publishing the same clip to the same account again creates a separate publishing task.

---

## FAQ

### Can I publish clips to multiple social accounts in one request?

Yes. Add one entry per connected social account ID in `publish_configs`. The keys must be account IDs returned by `/api/v2/social-media/accounts`, not platform names such as `youtube` or `tiktok`.

### Can I schedule a social media post instead of publishing immediately?

Yes. Pass `scheduled_at` as a Unix timestamp in milliseconds. The scheduled time must be at least 5 minutes in the future and no more than 30 days in the future.

### Do I need to export a clip before publishing it?

Yes. Social publishing requires an exported clip video. Create the clip with [AI Clipping](https://wayin.ai/api-docs/ai-clipping/) or [Find Moments](https://wayin.ai/api-docs/find-moments/) and submit the original task with `enable_export = true`.

### Which platforms are supported?

The API currently supports YouTube, TikTok, Instagram, Facebook, X / Twitter, and LinkedIn. Use [Connect a Social Media Account](#connect-a-social-media-account) with the platform value you want to authorize.

### Where can I monitor scheduled publishing tasks?

You can view publishing schedules and live task results on the [WayinVideo calendar](https://wayin.ai/wayinvideo/calendar).