# Social Media Publishing API

> Hubungkan akun media sosial, jadwalkan posting, dan publikasikan klip buatan AI ke YouTube, TikTok, Instagram, Facebook, X / Twitter, LinkedIn, dan lainnya.

## Social Media Publishing API

Gunakan Social Media Publishing API untuk menghubungkan akun media sosial dan mempublikasikan klip WayinVideo langsung ke akun tersebut.

API ini ditujukan untuk klip yang sudah diekspor dari [AI Clipping](https://wayin.ai/id/api-docs/ai-clipping/) dan [Find Moments](https://wayin.ai/id/api-docs/find-moments/). Buat klip dengan salah satu API tersebut terlebih dahulu, dan pastikan project awal dikirim dengan `enable_export = true`. Setelah itu gunakan `project_id` dan `idx` klip saat membuat tugas publikasi.

Alur umum:

1. Buat URL otorisasi OAuth untuk platform yang ingin dihubungkan.
2. Buka `auth_url` yang dikembalikan di browser dan selesaikan otorisasi.
3. Panggil endpoint akun untuk memastikan akun sudah terhubung dan salin `id`-nya.
4. Buat tugas publikasi dengan klip target dan konfigurasi publikasi untuk akun tersebut.

Semua endpoint memerlukan:

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

> **Billing:** Selama periode promosi terbatas, berhasil menghubungkan satu akun media sosial saat ini menggunakan **10 API Units**. Jika otorisasi tidak berhasil diselesaikan, API Units tidak akan dipotong.

---

## Endpoint

| Method | Path                                    | Deskripsi                                                                  |
| ------ | --------------------------------------- | -------------------------------------------------------------------------- |
| `POST` | `/api/v2/social-media/oauth/{platform}` | Membuat URL otorisasi OAuth sekali pakai untuk platform media sosial       |
| `GET`  | `/api/v2/social-media/accounts`         | Menampilkan daftar akun media sosial yang terhubung                        |
| `POST` | `/api/v2/social-media/publish`          | Membuat tugas untuk mempublikasikan klip ke satu atau beberapa akun        |
| `POST` | `/api/v2/social-media/schedule/{schedule_id}/cancel` | Membatalkan publikasi terjadwal yang belum dipublikasikan |

---

## Menghubungkan Akun Media Sosial

Buat URL otorisasi OAuth untuk platform yang ingin dihubungkan.

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

### Path Parameters

| Parameter  | Type   | Required | Deskripsi                                                                                                  |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `platform` | string | Ya       | Platform media sosial. Nilai yang didukung: `youtube`, `tiktok`, `twitter`, `instagram`, `facebook`, `linkedin`. |

### Request Body

Request body tidak diperlukan.

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

### Contoh Response

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

### Field Response

| Field      | Type   | Deskripsi                                                                                 |
| ---------- | ------ | ----------------------------------------------------------------------------------------- |
| `auth_url` | string | URL halaman otorisasi OAuth pihak ketiga. Buka URL ini di browser untuk memberi otorisasi. |
| `state`    | string | Identifier status otorisasi.                                                              |

### Catatan

- Setiap `auth_url` hanya dapat digunakan sekali. Jika otorisasi gagal atau URL kedaluwarsa, panggil endpoint ini lagi untuk membuat URL baru.
- Setelah otorisasi berhasil, panggil [Daftar Akun Media Sosial](#daftar-akun-media-sosial) untuk memastikan akun tersedia untuk publikasi.
- Anda dapat menghubungkan beberapa akun pada platform yang sama. Misalnya, panggil endpoint OAuth YouTube beberapa kali untuk menghubungkan beberapa channel YouTube.
- Jika akun tidak berhasil dihubungkan, API Units tidak akan dipotong.

---

## Daftar Akun Media Sosial

Dapatkan semua akun media sosial yang terhubung untuk pemilik API key saat ini. Gunakan endpoint ini sebelum publikasi untuk mendapatkan nilai `id` akun yang digunakan oleh `publish_configs`.

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

### Query Parameters

| Parameter     | Type    | Required | Default | Deskripsi                                                  |
| ------------- | ------- | -------- | ------- | ---------------------------------------------------------- |
| `active_only` | boolean | Tidak    | `false` | Jika `true`, hanya akun dengan token valid yang dikembalikan. |

### Contoh 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 Saat Tidak Ada Akun Terhubung

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

Jika `data` kosong, panggil [Menghubungkan Akun Media Sosial](#menghubungkan-akun-media-sosial) terlebih dahulu.

### Response Saat Ada Akun Terhubung

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

### Field Response

| Field                 | Type           | Deskripsi                                                                                                                 |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | string         | ID unik akun sosial. Gunakan sebagai key di `publish_configs` saat memanggil `/publish`. Jangan gunakan nama platform.   |
| `platform`            | string         | Identifier platform. Lihat [Nilai Platform](#nilai-platform).                                                             |
| `platform_username`   | string         | Username, nama channel, atau nama akun di platform.                                                                       |
| `platform_avatar`     | string \| null | URL gambar avatar akun.                                                                                                   |
| `token_valid`         | boolean        | `true` berarti token otorisasi valid dan akun dapat digunakan untuk publikasi.                                             |
| `token_expiring_soon` | boolean        | `true` berarti token otorisasi akan segera kedaluwarsa. Minta pengguna menghubungkan ulang akun tersebut.                 |

### Rekomendasi Penggunaan

- Sebelum membuat tugas publikasi, pastikan akun target memiliki `token_valid: true`.

---

## Membuat Tugas Publikasi

Publikasikan satu klip ke satu atau beberapa akun media sosial yang terhubung. Tentukan klip dengan mengirim ID project dan indeks klip.

> **Wajib:** `project_id` harus berasal dari tugas AI Clipping atau Find Moments yang dikirim dengan `enable_export = true`. Publikasi sosial membutuhkan video klip yang sudah diekspor; project yang dibuat tanpa export tidak dapat dipublikasikan dengan endpoint ini.

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

### Field Request

| Field             | Type            | Required | Deskripsi                                                                                              |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `project_id`      | string          | Ya       | ID project.                                                                                            |
| `idx`             | integer         | Ya       | Indeks klip di dalam project.                                                                          |
| `resolution`      | string          | Tidak    | Resolusi export yang digunakan oleh klip, seperti `1080p` atau `720p`.                                 |
| `publish_configs` | object          | Ya       | Konfigurasi publikasi dengan key berupa ID akun sosial dari endpoint akun.                             |
| `scheduled_at`    | integer \| null | Tidak    | Timestamp milidetik untuk publikasi terjadwal. Gunakan `null` atau hilangkan field ini untuk langsung publikasi. |

> **Cara membuat nilai `scheduled_at`**
>
> `scheduled_at` adalah Unix timestamp dalam milidetik. Nilainya harus setidaknya 5 menit di masa depan dan maksimal 30 hari di masa depan.
>
> Untuk menjadwalkan publikasi 10 menit dari sekarang dengan JavaScript:
>
> ```js
> const scheduledAt = Date.now() + 10 * 60 * 1000;
> ```
>
> Untuk menjadwalkan waktu tertentu:
>
> ```js
> const scheduledAt = new Date('2026-06-15T10:00:00Z').getTime();
> ```

### Konfigurasi Publikasi Platform

Setiap value dalam `publish_configs` adalah objek konfigurasi publikasi khusus platform.

| Field              | Type     | Required               | Deskripsi                                                                            |
| ------------------ | -------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `title`            | string   | Wajib bersyarat        | Judul video. Wajib untuk YouTube.                                                    |
| `description`      | string   | Wajib bersyarat        | Deskripsi video atau teks post. Wajib untuk TikTok.                                  |
| `tags`             | string[] | Tidak                  | Daftar tag.                                                                          |
| `visibility`       | string   | Tidak                  | Visibilitas: `public`, `private`, atau `unlisted`. Dukungan berbeda per platform.    |
| `thumbnail_url`    | string   | Tidak                  | URL gambar thumbnail kustom.                                                         |
| `category`         | string   | Tidak                  | Kategori video khusus platform.                                                      |
| `allow_comment`    | boolean  | Tidak                  | Apakah komentar diizinkan.                                                           |
| `allow_duet`       | boolean  | Tidak                  | Apakah duet diizinkan. Hanya TikTok.                                                 |
| `allow_stitch`     | boolean  | Tidak                  | Apakah stitch diizinkan. Hanya TikTok.                                               |
| `disclose_content` | boolean  | Tidak                  | Apakah konten promosi atau iklan perlu diungkapkan. Hanya TikTok.                    |

> **Penting:** Key di dalam `publish_configs` harus berupa ID akun yang dikembalikan oleh `/api/v2/social-media/accounts`, seperti `smacct06ixxxxxxx`. Jangan gunakan `youtube`, `tiktok`, atau nama platform lain sebagai key.

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

### Contoh Response

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

### Field Response

| Field          | Type            | Deskripsi                                                                        |
| -------------- | --------------- | -------------------------------------------------------------------------------- |
| `task_id`      | string          | ID unik tugas publikasi.                                                         |
| `status`       | string          | Status tugas publikasi. Lihat [Nilai Status Publikasi](#nilai-status-publikasi). |
| `created_at`   | integer         | Timestamp pembuatan tugas dalam milidetik.                                       |
| `schedule_id`  | string \| null  | ID jadwal. Dikembalikan saat `scheduled_at` diberikan.                           |
| `scheduled_at` | integer \| null | Timestamp publikasi terjadwal dalam milidetik.                                   |

Anda dapat melihat jadwal publikasi dan hasil tugas real-time di [kalender WayinVideo](https://wayin.ai/wayinvideo/calendar).

---

## Membatalkan Publikasi Terjadwal

Membatalkan publikasi terjadwal yang belum dipublikasikan. `schedule_id` berasal dari response [Membuat Tugas Publikasi](#membuat-tugas-publikasi) saat tugas dibuat dengan `scheduled_at`.

```
POST https://wayinvideo-api.wayin.ai/api/v2/social-media/schedule/{schedule_id}/cancel
```

> Endpoint ini hanya tersedia dengan prefix `/api/v2`. Tidak ada alias `/open/v2`.

### Path Parameters

| Parameter     | Type   | Wajib | Deskripsi  |
| ------------- | ------ | ----- | ---------- |
| `schedule_id` | string | Ya    | ID jadwal. |

### Request Body

Tidak memerlukan request body.

### Aturan Pembatalan

- Pembatalan tetap dapat dilakukan saat video klip masih diekspor. Setelah ekspor selesai, klip tidak akan dipublikasikan.
- Setelah dibatalkan, tugas platform yang belum mulai dipublikasikan berubah menjadi `CANCELLED`. Catatan tugas tetap disimpan.
- Jika semua platform sudah berhasil dipublikasikan, jadwal tidak dapat dibatalkan dan API mengembalikan `SMP-024`.
- Membatalkan ulang jadwal yang sudah dibatalkan juga mengembalikan sukses.
- Anda hanya dapat membatalkan tugas publikasi yang Anda buat sendiri. Jadwal dari Workspace lain dianggap tidak ada.

### Contoh Request

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

### Contoh Response

```json
{}
```

### Contoh Response Error

```json
{
  "message": "Not found sch_01HQ2X8J3K4L5M6N7O8P9Q0R",
  "trace_id": "trace_xxxxxxxxxxxxxxxx"
}
```

---

## Nilai Platform

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

## Nilai Status Publikasi

| Value          | Deskripsi                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------- |
| `PENDING`      | Tugas sudah dibuat dan menunggu penjadwalan.                                              |
| `SCHEDULED`    | Tugas sudah dijadwalkan dan menunggu waktu yang ditentukan.                               |
| `PROCESSING`   | Publikasi sedang berjalan, termasuk upload video dan pemrosesan di sisi platform.         |
| `DONE`         | Publikasi berhasil.                                                                       |
| `PARTIAL_DONE` | Sebagian akun berhasil dan sebagian gagal. Hanya mungkin saat publikasi ke beberapa akun. |
| `ERROR`        | Publikasi gagal.                                                                          |
| `CANCELLED`    | Publikasi dibatalkan.                                                                     |

---

## Contoh Alur Lengkap

### Langkah 1: Buat URL OAuth YouTube

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

Buka `auth_url` yang dikembalikan di browser dan selesaikan otorisasi.

### Langkah 2: Lihat Akun yang Tersedia

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

Salin `id` akun yang ingin digunakan untuk publikasi.

### Langkah 3: Publikasikan Klip

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

---

## Catatan

1. Key `publish_configs` adalah ID akun, bukan nama platform.
2. Untuk menjadwalkan publikasi, kirim `scheduled_at` sebagai timestamp milidetik di masa depan.
3. Klip yang sama dapat dipublikasikan beberapa kali ke akun berbeda. Publikasi ulang klip yang sama ke akun yang sama akan membuat tugas independen.
4. Publikasi sosial membutuhkan video klip yang sudah diekspor. Gunakan `project_id` dari tugas AI Clipping atau Find Moments yang dibuat dengan `enable_export = true`.
5. Jika publikasi mengembalikan error token akun, hubungkan ulang akun media sosial tersebut lalu coba lagi.
6. Untuk membatalkan publikasi terjadwal, panggil [Membatalkan Publikasi Terjadwal](#membatalkan-publikasi-terjadwal) dengan `schedule_id` yang dikembalikan saat tugas dibuat.
