# Social Media Publishing API

> Verbinden Sie Social-Media-Konten, planen Sie Posts und veröffentlichen Sie KI-generierte Clips auf YouTube, TikTok, Instagram, Facebook, X / Twitter, LinkedIn und weiteren Plattformen.

## Social Media Publishing API

Verwenden Sie die Social Media Publishing API, um Social-Media-Konten zu verbinden und WayinVideo-Clips direkt auf diesen Konten zu veröffentlichen.

Diese API ist für exportierte Clips gedacht, die mit [KI-Clipping](https://wayin.ai/de/api-docs/ai-clipping/) und [Momente finden](https://wayin.ai/de/api-docs/find-moments/) erstellt wurden. Erstellen Sie zuerst Clips mit einer dieser APIs und stellen Sie sicher, dass das ursprüngliche Projekt mit `enable_export = true` eingereicht wurde. Verwenden Sie danach die resultierende `project_id` und den Clip-`idx`, wenn Sie eine Veröffentlichungsaufgabe erstellen.

Typischer Ablauf:

1. Erstellen Sie eine OAuth-Autorisierungs-URL für die Plattform, die Sie verbinden möchten.
2. Öffnen Sie die zurückgegebene `auth_url` in einem Browser und schließen Sie die Autorisierung ab.
3. Rufen Sie den Konten-Endpoint auf, um das verbundene Konto zu bestätigen und dessen `id` zu kopieren.
4. Erstellen Sie eine Veröffentlichungsaufgabe mit dem Zielclip und den kontospezifischen Veröffentlichungseinstellungen.

Alle Endpoints erfordern:

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

> **Abrechnung:** Während der zeitlich begrenzten Promotion kostet das erfolgreiche Verbinden eines Social-Media-Kontos derzeit **10 API Units**. Wenn die Autorisierung nicht erfolgreich abgeschlossen wird, werden keine API Units abgezogen.

---

## Endpoints

| Methode | Pfad                                    | Beschreibung                                                                   |
| ------- | --------------------------------------- | ------------------------------------------------------------------------------ |
| `POST`  | `/api/v2/social-media/oauth/{platform}` | Erstellt eine einmalig nutzbare OAuth-Autorisierungs-URL für eine Plattform    |
| `GET`   | `/api/v2/social-media/accounts`         | Listet verbundene Social-Media-Konten auf                                      |
| `POST`  | `/api/v2/social-media/publish`          | Erstellt eine Aufgabe zur Veröffentlichung eines Clips auf verbundenen Konten   |
| `POST` | `/api/v2/social-media/schedule/{schedule_id}/cancel` | Storniert eine geplante Veröffentlichung, die noch nicht veröffentlicht wurde |

---

## Social-Media-Konto Verbinden

Erstellen Sie eine OAuth-Autorisierungs-URL für die Plattform, die Sie verbinden möchten.

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

### Pfadparameter

| Parameter  | Typ    | Erforderlich | Beschreibung                                                                                                  |
| ---------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `platform` | string | Ja           | Social-Media-Plattform. Erlaubte Werte: `youtube`, `tiktok`, `twitter`, `instagram`, `facebook`, `linkedin`. |

### Request Body

Es ist kein Request Body erforderlich.

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

### Beispiel-Response

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

### Response-Felder

| Feld       | Typ    | Beschreibung                                                                                         |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `auth_url` | string | URL der OAuth-Autorisierungsseite des Drittanbieters. Öffnen Sie diese URL im Browser zur Autorisierung. |
| `state`    | string | Autorisierungsstatus-Identifier.                                                                      |

### Hinweise

- Jede `auth_url` kann nur einmal verwendet werden. Wenn die Autorisierung fehlschlägt oder die URL abläuft, rufen Sie diesen Endpoint erneut auf, um eine neue URL zu erstellen.
- Nach erfolgreicher Autorisierung rufen Sie [Social-Media-Konten Auflisten](#social-media-konten-auflisten) auf, um zu bestätigen, dass das Konto für Veröffentlichungen verfügbar ist.
- Sie können mehrere Konten auf derselben Plattform verbinden. Rufen Sie zum Beispiel den YouTube-OAuth-Endpoint mehrfach auf, um mehrere YouTube-Kanäle zu verbinden.
- Wenn das Konto nicht erfolgreich verbunden wird, werden keine API Units abgezogen.

---

## Social-Media-Konten Auflisten

Rufen Sie alle verbundenen Social-Media-Konten des aktuellen API-Key-Inhabers ab. Verwenden Sie diesen Endpoint vor dem Veröffentlichen, um die Konto-`id`-Werte für `publish_configs` zu finden.

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

### Query-Parameter

| Parameter     | Typ     | Erforderlich | Standard | Beschreibung                                                          |
| ------------- | ------- | ------------ | -------- | --------------------------------------------------------------------- |
| `active_only` | boolean | Nein         | `false`  | Wenn `true`, werden nur Konten mit gültigen Tokens zurückgegeben.     |

### Beispiel-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, Wenn Kein Konto Verbunden Ist

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

Wenn `data` leer ist, rufen Sie zuerst [Social-Media-Konto Verbinden](#social-media-konto-verbinden) auf.

### Response, Wenn Konten Verbunden Sind

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

### Response-Felder

| Feld                  | Typ            | Beschreibung                                                                                                                        |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | string         | Eindeutige Social-Account-ID. Verwenden Sie diese als Key in `publish_configs` beim Aufruf von `/publish`. Nicht den Plattformnamen verwenden. |
| `platform`            | string         | Plattform-Identifier. Siehe [Plattformwerte](#plattformwerte).                                                                      |
| `platform_username`   | string         | Benutzername, Kanalname oder Kontoname auf der Plattform.                                                                           |
| `platform_avatar`     | string \| null | Avatarbild-URL des Kontos.                                                                                                          |
| `token_valid`         | boolean        | `true` bedeutet, dass das Autorisierungstoken gültig ist und das Konto zum Veröffentlichen verwendet werden kann.                  |
| `token_expiring_soon` | boolean        | `true` bedeutet, dass das Autorisierungstoken bald abläuft. Bitten Sie den Benutzer, das Konto erneut zu verbinden.                |

### Empfohlene Verwendung

- Bestätigen Sie vor dem Erstellen einer Veröffentlichungsaufgabe, dass das Zielkonto `token_valid: true` hat.

---

## Veröffentlichungsaufgabe Erstellen

Veröffentlichen Sie einen Clip auf einem oder mehreren verbundenen Social-Media-Konten. Identifizieren Sie den Clip über die Projekt-ID und den Clip-Index.

> **Erforderlich:** Die `project_id` muss aus einer KI-Clipping- oder Momente-finden-Aufgabe stammen, die mit `enable_export = true` eingereicht wurde. Social Publishing erfordert ein exportiertes Clip-Video; Projekte ohne aktivierten Export können mit diesem Endpoint nicht veröffentlicht werden.

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

### Request-Felder

| Feld              | Typ             | Erforderlich | Beschreibung                                                                                               |
| ----------------- | --------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `project_id`      | string          | Ja           | Projekt-ID.                                                                                                |
| `idx`             | integer         | Ja           | Clip-Index innerhalb des Projekts.                                                                         |
| `resolution`      | string          | Nein         | Exportauflösung des exportierten Clips, z. B. `1080p` oder `720p`.                                         |
| `publish_configs` | object          | Ja           | Veröffentlichungseinstellungen, deren Keys Social-Account-IDs aus dem Konten-Endpoint sind.                |
| `scheduled_at`    | integer \| null | Nein         | Millisekunden-Timestamp für geplante Veröffentlichung. Verwenden Sie `null` oder lassen Sie das Feld weg, um sofort zu veröffentlichen. |

> **So erzeugen Sie einen `scheduled_at`-Wert**
>
> `scheduled_at` ist ein Unix-Timestamp in Millisekunden. Er muss mindestens 5 Minuten und höchstens 30 Tage in der Zukunft liegen.
>
> Veröffentlichung in 10 Minuten mit JavaScript planen:
>
> ```js
> const scheduledAt = Date.now() + 10 * 60 * 1000;
> ```
>
> Für einen bestimmten Zeitpunkt planen:
>
> ```js
> const scheduledAt = new Date('2026-06-15T10:00:00Z').getTime();
> ```

### Plattform-Veröffentlichungskonfiguration

Jeder Wert in `publish_configs` ist ein plattformspezifisches Veröffentlichungsobjekt.

| Feld               | Typ      | Erforderlich             | Beschreibung                                                                                  |
| ------------------ | -------- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `title`            | string   | Bedingt erforderlich     | Videotitel. Für YouTube erforderlich.                                                         |
| `description`      | string   | Bedingt erforderlich     | Videobeschreibung oder Beitragstext. Für TikTok erforderlich.                                 |
| `tags`             | string[] | Nein                     | Tag-Liste.                                                                                    |
| `visibility`       | string   | Nein                     | Sichtbarkeit: `public`, `private` oder `unlisted`. Plattformunterstützung variiert.           |
| `thumbnail_url`    | string   | Nein                     | URL eines benutzerdefinierten Thumbnail-Bildes.                                                |
| `category`         | string   | Nein                     | Plattformspezifische Videokategorie.                                                          |
| `allow_comment`    | boolean  | Nein                     | Ob Kommentare erlaubt sind.                                                                   |
| `allow_duet`       | boolean  | Nein                     | Ob Duette erlaubt sind. Nur TikTok.                                                           |
| `allow_stitch`     | boolean  | Nein                     | Ob Stitches erlaubt sind. Nur TikTok.                                                         |
| `disclose_content` | boolean  | Nein                     | Ob Werbe- oder Promotionsinhalte offengelegt werden sollen. Nur TikTok.                       |

> **Wichtig:** Die Keys in `publish_configs` müssen Konto-IDs sein, die von `/api/v2/social-media/accounts` zurückgegeben wurden, z. B. `smacct06ixxxxxxx`. Verwenden Sie nicht `youtube`, `tiktok` oder andere Plattformnamen als Keys.

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

### Beispiel-Response

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

### Response-Felder

| Feld           | Typ             | Beschreibung                                                                                       |
| -------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `task_id`      | string          | Eindeutige Veröffentlichungsaufgaben-ID.                                                           |
| `status`       | string          | Status der Veröffentlichungsaufgabe. Siehe [Veröffentlichungsstatuswerte](#veröffentlichungsstatuswerte). |
| `created_at`   | integer         | Erstellungszeit der Aufgabe als Millisekunden-Timestamp.                                           |
| `schedule_id`  | string \| null  | Zeitplan-ID. Wird zurückgegeben, wenn `scheduled_at` angegeben wurde.                              |
| `scheduled_at` | integer \| null | Geplanter Veröffentlichungszeitpunkt als Millisekunden-Timestamp.                                  |

Sie können Veröffentlichungspläne und Live-Ergebnisse im [WayinVideo-Kalender](https://wayin.ai/wayinvideo/calendar) ansehen.

---

## Geplante Veröffentlichung Stornieren

Storniert eine geplante Veröffentlichung, die noch nicht veröffentlicht wurde. Die `schedule_id` stammt aus der Response von [Veröffentlichungsaufgabe Erstellen](#veröffentlichungsaufgabe-erstellen), wenn die Aufgabe mit `scheduled_at` erstellt wurde.

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

> Dieser Endpoint ist nur unter dem Präfix `/api/v2` verfügbar. Es gibt keinen `/open/v2`-Alias.

### Pfadparameter

| Parameter     | Typ    | Erforderlich | Beschreibung |
| ------------- | ------ | ------------ | ------------ |
| `schedule_id` | string | Ja           | Zeitplan-ID. |

### Request Body

Es ist kein Request Body erforderlich.

### Stornierungsregeln

- Sie können auch stornieren, während das Clip-Video noch exportiert wird. Nach Abschluss des Exports wird der Clip nicht veröffentlicht.
- Nach der Stornierung wechseln Plattformaufgaben, deren Veröffentlichung noch nicht begonnen hat, zu `CANCELLED`. Die Aufgabendatensätze bleiben erhalten.
- Wenn bereits alle Plattformen erfolgreich veröffentlicht wurden, kann der Zeitplan nicht storniert werden und die API gibt `SMP-024` zurück.
- Das erneute Stornieren eines bereits stornierten Zeitplans gibt ebenfalls Erfolg zurück.
- Sie können nur selbst erstellte Veröffentlichungsaufgaben stornieren. Zeitpläne anderer Workspaces werden als nicht vorhanden behandelt.

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

### Beispiel-Response

```json
{}
```

### Beispiel-Fehlerresponse

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

---

## Plattformwerte

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

## Veröffentlichungsstatuswerte

| Wert           | Beschreibung                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------- |
| `PENDING`      | Die Aufgabe wurde erstellt und wartet auf Planung.                                            |
| `SCHEDULED`    | Die Aufgabe wurde geplant und wartet auf den geplanten Zeitpunkt.                             |
| `PROCESSING`   | Die Veröffentlichung läuft, inklusive Video-Upload und Verarbeitung auf Plattformseite.       |
| `DONE`         | Die Veröffentlichung war erfolgreich.                                                         |
| `PARTIAL_DONE` | Einige Konten waren erfolgreich und andere sind fehlgeschlagen. Nur bei mehreren Konten möglich. |
| `ERROR`        | Die Veröffentlichung ist fehlgeschlagen.                                                      |
| `CANCELLED`    | Die Veröffentlichung wurde abgebrochen.                                                       |

---

## Vollständiges Ablaufbeispiel

### Schritt 1: YouTube-OAuth-URL Erstellen

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

Öffnen Sie die zurückgegebene `auth_url` im Browser und schließen Sie die Autorisierung ab.

### Schritt 2: Verfügbare Konten Auflisten

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

Kopieren Sie die `id` des Kontos, auf dem Sie veröffentlichen möchten.

### Schritt 3: Clip Veröffentlichen

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

---

## Hinweise

1. Die Keys von `publish_configs` sind Konto-IDs, keine Plattformnamen.
2. Für geplante Veröffentlichungen übergeben Sie `scheduled_at` als zukünftigen Millisekunden-Timestamp.
3. Derselbe Clip kann mehrfach auf verschiedenen Konten veröffentlicht werden. Eine erneute Veröffentlichung desselben Clips auf demselben Konto erstellt eine unabhängige Aufgabe.
4. Social Publishing erfordert ein exportiertes Clip-Video. Verwenden Sie die `project_id` einer KI-Clipping- oder Momente-finden-Aufgabe, die mit `enable_export = true` erstellt wurde.
5. Wenn beim Veröffentlichen ein Konto-Token-Fehler zurückgegeben wird, verbinden Sie das Social-Media-Konto erneut und versuchen Sie es noch einmal.
6. Um eine geplante Veröffentlichung zu stornieren, rufen Sie [Geplante Veröffentlichung Stornieren](#geplante-veröffentlichung-stornieren) mit der beim Erstellen der Aufgabe zurückgegebenen `schedule_id` auf.
