# Publica en las redes

> Publica uno o varios clips editados en varias cuentas a la vez, ahora o programado, y sigue cada publicación.

Un **post** publica ediciones en cuentas conectadas. Cada par edición y cuenta se convierte en un **elemento**, con estado propio: en un post para TikTok y YouTube, un elemento puede salir y el otro fallar.

No necesitas renderizar antes. El post renderiza lo que falta y publica.

## Elige las cuentas

```bash
curl https://api.cut.pro/api/v1/connections \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Cada conexión trae `id`, `platform`, `username` y números de la audiencia. El `id` es el `connection_id` del post. Si la cuenta que la persona quiere no está en la lista, pide el enlace de conexión y entrégaselo:

```bash
curl "https://api.cut.pro/api/v1/connections/link?platform=tiktok" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

La conexión la hace el dueño de la cuenta, en el navegador. Cuando vuelva, lista de nuevo.

## Crea el post

```bash
curl -X POST https://api.cut.pro/api/v1/posts \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "edit_id": "7412910087700001",
        "targets": [
          {
            "connection_id": "7390012299881100",
            "metadata": { "tiktok": { "title": "El estribillo que todo el mundo conoce #musica", "privacyLevel": "PUBLIC_TO_EVERYONE" } }
          },
          {
            "connection_id": "7390012299881200",
            "metadata": { "youtube": { "title": "El estribillo que todo el mundo conoce", "categoryId": "10", "privacyStatus": "public" } }
          }
        ]
      }
    ],
    "scheduled_at": "2026-10-30T12:00:00.000Z"
  }'
```

```json title="201 Created"
{ "id": "7412930011223344", "item_count": 2, "scheduled_at": "2026-10-30T12:00:00.000Z", "status": "pending" }
```

- `edit_id` viene del clip, del render o de un [video generado](/es/generations). Varios `videos` en un solo post publican varios clips a la vez.
- `scheduled_at` programa, en ISO 8601 en el futuro. Sin él, publica ahora.

## Metadata por red

`metadata` lleva una clave con el nombre de la red y, dentro, los campos propios de la red, con sus nombres (`privacyLevel`, `categoryId`). Es la única parte de la API fuera de `snake_case`: el contenido sigue a la red tal como está.

| Red | Obligatorios | Otros campos |
|---|---|---|
| `youtube` | `title`, `categoryId`, `privacyStatus` | `description`, `tags`, `madeForKids`, `notifySubscribers`, `license`, `embeddable` |
| `tiktok` | `title`, `privacyLevel` | `disableDuet`, `disableComment`, `disableStitch`, `brandContentToggle`, `brandOrganicToggle`, `isAigc` |
| `instagram` | | `caption`, `shareToFeed`, `collaborators`, `userTags`, `audioName`, `thumbOffset`, `trialReel`, `firstComment` |
| `facebook` | | `description`, `postType` (`reel` o `feed`), `videoTitle`, `link`, `firstComment` |
| `threads` | | `text`, `replyControl`, `firstComment` |
| `twitter` | | `text`, `replySettings` |
| `linkedin` | `text` | `visibility` |
| `pinterest` | `boardId`, `title`, `description` | `link`, `coverImageUrl` |
| `bluesky` | | `text`, `languages` |

Todas aceptan `coverImageId` para la portada. Los límites de cada campo, y las demás redes, están en [`POST /posts`](/reference). Una red que aún está llegando rechaza la solicitud entera con `400 PLATFORM_UNAVAILABLE`, antes de crear nada.

## Sigue el post

```bash
curl https://api.cut.pro/api/v1/posts/7412930011223344 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Cada elemento pasa por `pending` → `rendering` → `publishing` → `completed` o `failed`. En `completed`, `published_url` es el enlace del video en la red. En `failed`, `error_code` dice el motivo.

El post resume los elementos:

| `status` del post | Significa |
|---|---|
| `pending` | Programado o esperando empezar. |
| `processing` | Elementos renderizando o publicando. |
| `completed` | Todos los elementos publicados. |
| `partial` | Una parte se publicó, otra falló. Trátalo como aviso, no como éxito. |
| `failed` | Ningún elemento se publicó. |
| `cancelled` | Cancelado. |

Consulta cada 10 a 30 segundos. Un elemento que falló vuelve a la cola con:

```bash
curl -X POST https://api.cut.pro/api/v1/posts/7412930011223344/items/7412930011223401/retry \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

## Cambia, adelanta o cancela

| Ruta | Qué hace |
|---|---|
| `PATCH /posts/{id}` | Cambia `scheduled_at` (mínimo 1 minuto adelante, o `null` para publicar ya) mientras todo elemento esté `pending`. Con `items`, reemplaza el conjunto de elementos pendientes: con `item_id` actualiza, sin él inserta, ausente elimina. Los elementos publicados no cambian. |
| `POST /posts/{id}/publish` | Publica ahora un post programado, o destraba uno que quedó detenido. |
| `DELETE /posts/{id}` | Cancela todos los elementos que aún no salieron. Lo que ya está al aire sigue al aire. |
| `DELETE /posts/{id}/items/{itemId}` | Cancela un elemento `pending`, `rendering` o `failed`. En un elemento `completed`, elimina el video de la red, en las redes que lo permiten. Un elemento en `publishing` ya no se puede detener. |

> Eliminar un elemento publicado quita el video de la cuenta de la persona en la red. Si la red lo rechaza, la respuesta es `400` con el motivo (`DELETE_NOT_SUPPORTED`, `PERMISSION_MISSING`, `DELETE_LIMIT_REACHED`) y nada cambia.

## Errores

| Code | Cuándo |
|---|---|
| `INVALID_METADATA` | Un campo de la red está mal o falta. `extra.field` y `extra.platform` dicen cuál. |
| `INVALID_CONNECTIONS` | Conexión inexistente o desconectada. `extra.invalid_connections` lista cuáles. Pide reconectar con `GET /connections/link`. |
| `EDITS_NOT_FOUND` | Edición que no es de este workspace, en `extra.invalid_edits`. |
| `DAILY_LIMIT_EXCEEDED` | La cuenta superó el límite diario de posts de la red. `extra` trae `daily_limit`, `used_today` y la conexión. |
| `DUPLICATE_POST` | La misma solicitud (mismas ediciones, cuentas y horario) llegó de nuevo justo después de la primera. Vale la primera: no repitas. |
| `MEDIA_REFUNDED` | La edición es de un video generado con IA que fue reembolsado. |
| `RECORDING_EXPIRED` | La edición es de un clip de transmisión en vivo cuya grabación expiró. |
| `INVALID_SCHEDULED_AT` | Horario en el pasado o fuera del formato ISO 8601. |