Posts
Subir videos grandes para usar en posts con la API
Los posts reciben el medio por URL. Si no tienes dónde alojar el archivo, envíalo a Connect y recibe una URL en un dominio que las redes aceptan. Hasta 8 MB va en una sola solicitud; por encima, el video se sube por partes, hasta 1 GB, y usas la URL en media.url de POST /posts.
La llamada
POST /api/media/uploads
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"file_name": "reels-summer.mp4",
"size": 52428800
}Qué puedes hacer
- Subir un archivo de hasta 8 MB en una sola solicitud con POST /media.
- Abrir un upload por partes con POST /media/uploads para archivos de hasta 1 GB.
- Enviar las partes con PUT /media/uploads/{uuid}/parts/{part}, en paralelo después de la parte 1.
- Retomar un envío interrumpido: GET /media/uploads/{uuid} dice qué partes ya llegaron.
- Terminar con POST /media/uploads/{uuid}/complete y recibir la URL lista para usar en un post.
Reglas y límites
- POST /media acepta hasta 8 MB. Por encima responde 413 media_too_large_for_single_upload y el envío va por partes.
- Connect lee el tipo del archivo en la parte 1. La parte 1 va primero; las demás pueden ir en cualquier orden y a la vez. Reenviar una parte reemplaza la anterior.
- Cada parte exige un Content-Length igual a su tamaño exacto (upload.part_size, o el resto en la última). Sin él, la respuesta es 411.
- Acepta JPEG, PNG, WebP y GIF (imágenes de hasta 30 MB), MP4 y MOV (hasta 1 GB). El tipo sale del contenido, no del nombre, y el archivo entero se verifica al completar (422 media_content_invalid si no es válido).
- La URL vale hasta expires_at, 30 días después de que el medio queda ready, y luego el archivo se borra. Quien tenga el enlace puede leer el archivo, así que pásalo solo a quien va a publicar.
- POST /media y POST /media/uploads exigen el header Idempotency-Key. Hasta 20 uploads abiertos por cliente.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file_name | string | Sí | El nombre del archivo (hasta 255 caracteres). |
| size | integer | Sí | El tamaño exacto del archivo en bytes, de 1 hasta 1073741824 (1 GB). |
| upload.part_size | integer | No | En la respuesta: los bytes de cada parte. La última lleva el resto. |
| upload.parts | integer | No | En la respuesta: cuántas partes tiene el archivo, numeradas desde 1. |
| upload.expires_at | string | No | En la respuesta: hasta cuándo se puede completar el upload. Después se descartan las partes. |
| received_parts | array | No | En GET /media/uploads/{uuid}: las partes ya recibidas, para retomar un envío interrumpido. |
| url | string | No | Cuando status es ready: la URL pública para usar en media.url de POST /posts. |
| expires_at | string | No | Cuándo la URL deja de valer y se borra el archivo: 30 días después de que el medio queda ready. |
Para quién
SaaS de edición de video
El usuario exporta un Reels de 200 MB; el producto lo sube por partes y publica en Instagram y Facebook con la URL devuelta.
Agencia con videos pesados
El panel sube los videos de la campaña una vez y reutiliza la misma URL en posts de varias redes.
Agente de IA de video
El agente genera un video, lo sube a Connect por partes y pasa la URL a POST /posts sin alojar nada.
Funciona con
Instagram Business
Facebook
YouTube
LinkedIn
Threads
Pinterest
Preguntas frecuentes
¿Cuál es el tamaño máximo?
Hasta 8 MB en una sola solicitud (POST /media) y hasta 1 GB por partes (POST /media/uploads). Las imágenes tienen un límite de 30 MB.
¿Cuánto tiempo queda activa la URL?
30 días desde que el medio queda ready. Después el archivo se borra, así que usa la URL en un post dentro de ese plazo.
¿Qué pasa si el envío se corta a la mitad?
Consulta GET /media/uploads/{uuid}: received_parts lista las partes recibidas. Envía solo las que faltan y completa. El envío sigue abierto hasta upload.expires_at.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
