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

CampoTipoObligatorioDescripción
file_namestringSíEl nombre del archivo (hasta 255 caracteres).
sizeintegerSíEl tamaño exacto del archivo en bytes, de 1 hasta 1073741824 (1 GB).
upload.part_sizeintegerNoEn la respuesta: los bytes de cada parte. La última lleva el resto.
upload.partsintegerNoEn la respuesta: cuántas partes tiene el archivo, numeradas desde 1.
upload.expires_atstringNoEn la respuesta: hasta cuándo se puede completar el upload. Después se descartan las partes.
received_partsarrayNoEn GET /media/uploads/{uuid}: las partes ya recibidas, para retomar un envío interrumpido.
urlstringNoCuando status es ready: la URL pública para usar en media.url de POST /posts.
expires_atstringNoCuá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.

Relacionadas

Ver todo lo que puedes hacer con Posts

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.