Publicando en las redes
Cómo publicar clips renderizados en TikTok, Instagram, YouTube y más
Después de renderizar un clip puedes publicarlo en una o varias cuentas conectadas con POST /posts. Una sola publicación puede llevar varios clips a varias cuentas de una vez.
Antes de empezar
Necesitas dos cosas:
Un clip renderizado
El edit_id viene del render: es lo que identifica el vídeo a publicar, y nunca caduca.
Cuentas conectadas
El connection_id viene de GET /connections. Conecta cuentas nuevas con el OAuth dentro de cut.pro: la API no conecta cuentas.
Cómo se arma el cuerpo
Cada elemento de videos apunta un clip (edit_id) a uno o más destinos (targets). Cada destino combina una conexión (connection_id) con la metadata de esa plataforma (título, privacidad, etc.).
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": "EDIT_ID",
"targets": [
{
"connection_id": "CONEXION_TIKTOK",
"metadata": {
"tiktok": {
"title": "Mi corte viral",
"privacyLevel": "PUBLIC_TO_EVERYONE"
}
}
},
{
"connection_id": "CONEXION_YOUTUBE",
"metadata": {
"youtube": {
"title": "Mi corte viral",
"description": "Cortes del episodio de hoy",
"categoryId": "22",
"privacyStatus": "public"
}
}
}
]
}
]
}'{
"id": "7412909001223344",
"item_count": 2,
"scheduled_at": null,
"status": "pending"
}La metadata cambia según la plataforma (TikTok, YouTube, Instagram, Threads, Bluesky, LinkedIn, Pinterest, Facebook). Los campos obligatorios y las opciones de cada una están detallados en la página del endpoint POST /posts, con el playground interactivo.
Para programar en vez de publicar ya, envía scheduled_at con una fecha ISO 8601 en el futuro.
Sigue la publicación
La publicación entra en la cola y publica de forma asíncrona. Haz polling en GET /posts/{id}:
curl https://api.cut.pro/api/v1/posts/POST_ID \
-H "X-Api-Key: $CUTPRO_API_KEY"El status de la publicación evoluciona así:
| Estado | Significado |
|---|---|
pending | En cola, todavía no empezó |
processing | Publicando en las cuentas |
completed | Todos los elementos publicaron |
partial | Algunos publicaron y otros fallaron |
failed | Ningún elemento publicó |
El array items muestra el resultado por cuenta, útil cuando el estado es partial.
Cuando algo falla
Los elementos fallan de forma independiente: un destino con error no tumba a los que ya publicaron.
- Reintentar un elemento que falló:
POST /posts/{id}/items/{itemId}/retry - Quitar un elemento sin tocar los demás:
DELETE /posts/{id}/items/{itemId} - Borrar la publicación entera:
DELETE /posts/{id} - Editar antes de publicar (por ejemplo, ajustar la programación):
PATCH /posts/{id}
partial no es éxito. Si tu producto dice "publicado" en un partial, le está mintiendo al usuario: lee items y muestra qué subió y qué no.
Los rechazos que ocurren antes de que se cree nada:
code | Estado | Qué hacer |
|---|---|---|
INVALID_CONNECTIONS | 400 | extra.invalid_connections lista las conexiones desconocidas, revocadas o que no publican vídeo |
INVALID_METADATA | 400 | extra.field dice qué campo no pasó, como youtube.categoryId |
PLATFORM_UNAVAILABLE | 400 | Esa red todavía no está abierta para publicar |
EDITS_NOT_FOUND | 404 | extra.invalid_edits lista los edit_id que no existen en este workspace |
DAILY_LIMIT_EXCEEDED | 403 | La cuenta llegó al techo diario de la plataforma. El extra trae daily_limit, used_today y cuántos elementos sumaría esta petición |
DUPLICATE_POST | 409 | El mismo clip ya va camino de la misma cuenta |
El archivo se va, el edit se queda
Cada elemento trae un render_id, y pasa a null cuando la retención de tu plan borra el archivo renderizado. La publicación sigue ahí, con el published_url y la metadata exacta que se publicó. Para recuperar el MP4, llama a POST /renders con el edit_id del elemento (mira Recetas).