# API de Publicación en Redes Sociales

> Conecta cuentas sociales, programa publicaciones y publica clips generados por IA en YouTube, TikTok, Instagram, Facebook, X / Twitter, LinkedIn y más.

## API de Publicación en Redes Sociales

Usa la API de Publicación en Redes Sociales para conectar cuentas de redes sociales y publicar clips de WayinVideo directamente en esas cuentas.

Esta API está diseñada para clips exportados generados por [Clipping con IA](https://wayin.ai/es/api-docs/ai-clipping/) y [Buscar Momentos](https://wayin.ai/es/api-docs/find-moments/). Primero crea clips con una de esas APIs y asegúrate de que el proyecto original se haya enviado con `enable_export = true`. Después usa el `project_id` resultante y el `idx` del clip al crear una tarea de publicación.

Flujo típico:

1. Crea una URL de autorización OAuth para la plataforma que quieres conectar.
2. Abre el `auth_url` devuelto en un navegador y completa la autorización.
3. Llama al endpoint de cuentas para confirmar la cuenta conectada y copiar su `id`.
4. Crea una tarea de publicación con el clip de destino y la configuración específica de la cuenta.

Todos los endpoints requieren:

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

> **Facturación:** Durante el periodo promocional por tiempo limitado, conectar correctamente una cuenta de red social consume actualmente **10 API Units**. Si la autorización no se completa correctamente, no se descuentan API Units.

---

## Endpoints

| Método | Ruta                                    | Descripción                                                                 |
| ------ | --------------------------------------- | --------------------------------------------------------------------------- |
| `POST` | `/api/v2/social-media/oauth/{platform}` | Crea una URL OAuth de un solo uso para una plataforma de red social         |
| `GET`  | `/api/v2/social-media/accounts`         | Lista las cuentas de redes sociales conectadas                              |
| `POST` | `/api/v2/social-media/publish`          | Crea una tarea para publicar un clip en una o más cuentas conectadas        |
| `POST` | `/api/v2/social-media/schedule/{schedule_id}/cancel` | Cancela una publicación programada que aún no se ha publicado |

---

## Conectar una Cuenta de Red Social

Crea una URL de autorización OAuth para la plataforma que quieres conectar.

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

### Parámetros de Ruta

| Parámetro  | Tipo   | Obligatorio | Descripción                                                                                                  |
| ---------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `platform` | string | Sí          | Plataforma de red social. Valores permitidos: `youtube`, `tiktok`, `twitter`, `instagram`, `facebook`, `linkedin`. |

### Cuerpo de la Solicitud

No se requiere cuerpo de solicitud.

### Ejemplo de Solicitud

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

### Ejemplo de Respuesta

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

### Campos de Respuesta

| Campo      | Tipo   | Descripción                                                                                         |
| ---------- | ------ | --------------------------------------------------------------------------------------------------- |
| `auth_url` | string | URL de la página OAuth de terceros. Abre esta URL en un navegador para autorizar la cuenta.         |
| `state`    | string | Identificador de estado de autorización.                                                            |

### Notas

- Cada `auth_url` solo puede usarse una vez. Si la autorización falla o la URL caduca, llama de nuevo a este endpoint para crear una URL nueva.
- Cuando la autorización se complete correctamente, llama a [Listar Cuentas de Redes Sociales](#listar-cuentas-de-redes-sociales) para confirmar que la cuenta está disponible para publicar.
- Puedes conectar varias cuentas en la misma plataforma. Por ejemplo, llama varias veces al endpoint OAuth de YouTube para conectar varios canales de YouTube.
- Si la cuenta no se conecta correctamente, no se descuentan API Units.

---

## Listar Cuentas de Redes Sociales

Obtén todas las cuentas de redes sociales conectadas al propietario de la API key actual. Usa este endpoint antes de publicar para encontrar los valores de `id` que se usan en `publish_configs`.

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

### Parámetros de Consulta

| Parámetro     | Tipo    | Obligatorio | Predeterminado | Descripción                                                 |
| ------------- | ------- | ----------- | -------------- | ----------------------------------------------------------- |
| `active_only` | boolean | No          | `false`        | Cuando es `true`, solo devuelve cuentas con tokens válidos. |

### Ejemplo de Solicitud

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

### Respuesta Cuando No Hay Ninguna Cuenta Conectada

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

Si `data` está vacío, llama primero a [Conectar una Cuenta de Red Social](#conectar-una-cuenta-de-red-social).

### Respuesta Cuando Hay Cuentas Conectadas

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

### Campos de Respuesta

| Campo                 | Tipo           | Descripción                                                                                                                         |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | string         | ID único de la cuenta social. Úsalo como clave en `publish_configs` al llamar a `/publish`. No uses el nombre de la plataforma.    |
| `platform`            | string         | Identificador de plataforma. Consulta [Valores de Plataforma](#valores-de-plataforma).                                             |
| `platform_username`   | string         | Nombre de usuario, canal o cuenta en la plataforma.                                                                                 |
| `platform_avatar`     | string \| null | URL de la imagen de avatar de la cuenta.                                                                                            |
| `token_valid`         | boolean        | `true` significa que el token de autorización es válido y la cuenta puede usarse para publicar.                                     |
| `token_expiring_soon` | boolean        | `true` significa que el token de autorización caducará pronto. Pide al usuario que vuelva a conectar la cuenta.                    |

### Uso Recomendado

- Antes de crear una tarea de publicación, confirma que la cuenta de destino tenga `token_valid: true`.

---

## Crear una Tarea de Publicación

Publica un clip en una o más cuentas de redes sociales conectadas. Identifica el clip enviando el ID del proyecto y el índice del clip.

> **Obligatorio:** El `project_id` debe provenir de una tarea de Clipping con IA o Buscar Momentos enviada con `enable_export = true`. La publicación social requiere un video de clip exportado; los proyectos creados sin exportación habilitada no se pueden publicar con este endpoint.

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

### Campos de Solicitud

| Campo             | Tipo            | Obligatorio | Descripción                                                                                              |
| ----------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `project_id`      | string          | Sí          | ID del proyecto.                                                                                         |
| `idx`             | integer         | Sí          | Índice del clip dentro del proyecto.                                                                     |
| `resolution`      | string          | No          | Resolución de exportación usada por el clip exportado, como `1080p` o `720p`.                            |
| `publish_configs` | object          | Sí          | Configuración de publicación indexada por el ID de cuenta social devuelto por el endpoint de cuentas.    |
| `scheduled_at`    | integer \| null | No          | Timestamp en milisegundos para publicación programada. Usa `null` u omite este campo para publicar ahora. |

> **Cómo generar un valor `scheduled_at`**
>
> `scheduled_at` es un timestamp Unix en milisegundos. Debe estar al menos 5 minutos en el futuro y no más de 30 días en el futuro.
>
> Para programar la publicación 10 minutos desde ahora en JavaScript:
>
> ```js
> const scheduledAt = Date.now() + 10 * 60 * 1000;
> ```
>
> Para programar una hora específica:
>
> ```js
> const scheduledAt = new Date('2026-06-15T10:00:00Z').getTime();
> ```

### Configuración de Publicación de Plataforma

Cada valor dentro de `publish_configs` es un objeto de configuración de publicación específico de la plataforma.

| Campo              | Tipo     | Obligatorio                | Descripción                                                                            |
| ------------------ | -------- | -------------------------- | -------------------------------------------------------------------------------------- |
| `title`            | string   | Condicionalmente obligatorio | Título del video. Obligatorio para YouTube.                                           |
| `description`      | string   | Condicionalmente obligatorio | Descripción del video o texto de la publicación. Obligatorio para TikTok.             |
| `tags`             | string[] | No                         | Lista de etiquetas.                                                                    |
| `visibility`       | string   | No                         | Visibilidad: `public`, `private` o `unlisted`. El soporte varía por plataforma.       |
| `thumbnail_url`    | string   | No                         | URL de imagen de miniatura personalizada.                                              |
| `category`         | string   | No                         | Categoría de video específica de la plataforma.                                        |
| `allow_comment`    | boolean  | No                         | Si se permiten comentarios.                                                            |
| `allow_duet`       | boolean  | No                         | Si se permiten duetos. Solo TikTok.                                                    |
| `allow_stitch`     | boolean  | No                         | Si se permiten stitches. Solo TikTok.                                                  |
| `disclose_content` | boolean  | No                         | Si se debe declarar contenido promocional o publicitario. Solo TikTok.                |

> **Importante:** Las claves dentro de `publish_configs` deben ser IDs de cuenta devueltos por `/api/v2/social-media/accounts`, como `smacct06ixxxxxxx`. No uses `youtube`, `tiktok` ni otros nombres de plataforma como claves.

### Ejemplo de Solicitud

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

### Ejemplo de Respuesta

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

### Campos de Respuesta

| Campo          | Tipo            | Descripción                                                                                  |
| -------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `task_id`      | string          | ID único de la tarea de publicación.                                                         |
| `status`       | string          | Estado de la tarea de publicación. Consulta [Valores de Estado de Publicación](#valores-de-estado-de-publicación). |
| `created_at`   | integer         | Timestamp de creación de la tarea en milisegundos.                                           |
| `schedule_id`  | string \| null  | ID de programación. Se devuelve cuando se proporciona `scheduled_at`.                         |
| `scheduled_at` | integer \| null | Timestamp de publicación programada en milisegundos.                                         |

Puedes ver las programaciones de publicación y los resultados en tiempo real en el [calendario de WayinVideo](https://wayin.ai/wayinvideo/calendar).

---

## Cancelar una Publicación Programada

Cancela una publicación programada que aún no se ha publicado. El `schedule_id` proviene de la respuesta de [Crear una Tarea de Publicación](#crear-una-tarea-de-publicación) cuando la tarea se creó con `scheduled_at`.

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

> Este endpoint solo está disponible con el prefijo `/api/v2`. No existe un alias `/open/v2`.

### Parámetros de Ruta

| Parámetro     | Tipo   | Obligatorio | Descripción          |
| ------------- | ------ | ----------- | -------------------- |
| `schedule_id` | string | Sí          | ID de programación. |

### Cuerpo de la Solicitud

No se requiere cuerpo de solicitud.

### Reglas de Cancelación

- Puedes cancelar mientras el video del clip todavía se está exportando. Cuando termine la exportación, el clip no se publicará.
- Tras la cancelación, las tareas de plataforma que aún no han empezado a publicarse cambian a `CANCELLED`. Los registros de las tareas se conservan.
- Si todas las plataformas ya se publicaron correctamente, la programación no se puede cancelar y la API devuelve `SMP-024`.
- Cancelar de nuevo una programación ya cancelada también devuelve éxito.
- Solo puedes cancelar tareas de publicación creadas por ti. Las programaciones de otros Workspaces se tratan como inexistentes.

### Ejemplo de Solicitud

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

### Ejemplo de Respuesta

```json
{}
```

### Ejemplo de Respuesta de Error

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

---

## Valores de Plataforma

| Valor       | Plataforma  | Sitio                 |
| ----------- | ----------- | --------------------- |
| `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  |

## Valores de Estado de Publicación

| Valor          | Descripción                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `PENDING`      | La tarea se creó y está esperando ser programada.                                                 |
| `SCHEDULED`    | La tarea fue programada y está esperando la hora programada.                                      |
| `PROCESSING`   | La publicación está en curso, incluido el upload del video y el procesamiento de la plataforma.   |
| `DONE`         | La publicación se completó correctamente.                                                         |
| `PARTIAL_DONE` | Algunas cuentas tuvieron éxito y otras fallaron. Solo es posible al publicar en varias cuentas.   |
| `ERROR`        | La publicación falló.                                                                             |
| `CANCELLED`    | La publicación fue cancelada.                                                                     |

---

## Ejemplo de Flujo Completo

### Paso 1: Crear una URL OAuth de 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 ''
```

Abre el `auth_url` devuelto en un navegador y completa la autorización.

### Paso 2: Listar Cuentas Disponibles

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

Copia el `id` de la cuenta en la que quieres publicar.

### Paso 3: Publicar un 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
  }'
```

---

## Notas

1. Las claves de `publish_configs` son IDs de cuenta, no nombres de plataforma.
2. Para programar una publicación, envía `scheduled_at` como un timestamp futuro en milisegundos.
3. El mismo clip puede publicarse varias veces en diferentes cuentas. Publicar de nuevo el mismo clip en la misma cuenta crea una tarea independiente.
4. La publicación social requiere un video de clip exportado. Usa el `project_id` de una tarea de Clipping con IA o Buscar Momentos creada con `enable_export = true`.
5. Si la publicación devuelve un error de token de cuenta, vuelve a conectar esa cuenta de red social e inténtalo de nuevo.
6. Para cancelar una publicación programada, llama a [Cancelar una Publicación Programada](#cancelar-una-publicación-programada) con el `schedule_id` devuelto al crear la tarea.
