Todos los límites que la API de Reels de Instagram impone a tu vídeo

¿Qué acepta la API de Reels de Instagram?

Un vídeo empujado a través de la API de Reels de Instagram tiene que superar cada línea de un bloque de especificaciones publicado antes de que Meta lo transcodifique, y ese bloque está en un solo sitio: Reel Specifications, en la referencia de IG User Media. Salta una y el contenedor que creaste con media_type=REELS vuelve con status_code en ERROR en lugar de FINISHED.

Esta es la lista entera, copiada de la referencia de Meta.

¿Cuánto puede durar un reel a través de la API?

Quince minutos. La línea de Meta es "Duration: 15 mins maximum, 3 seconds minimum," que sitúa el techo de la API mucho más arriba de lo que casi nadie espera y el suelo más arriba de lo que casi nadie se fija.

El mínimo de tres segundos es el que muerde. Un clip recortado a dos segundos y medio es un archivo perfectamente normal en cualquier otro sitio de internet y aquí es un rechazo instantáneo. No hay nota parcial ni relleno añadido por parte de Meta.

El techo de quince minutos merece una advertencia que Meta no le pone. Ese número gobierna lo que la API admitirá dentro de un contenedor. No dice nada sobre lo que la app de Instagram dejará subir a una persona desde el móvil, ni sobre lo que el sistema de recomendación hará con un reel de catorce minutos una vez exista. Meta sí pone exactamente ese tipo de aviso en el parámetro share_to_feed, señalando que ninguno de los dos valores "determines whether the reel actually appears in the Reels tab because the reel may not meet eligibilty requirements or may not be selected by our algorithm." Que la API acepte un archivo y que Instagram lo distribuya son dos preguntas distintas.

¿Cómo de grande puede ser el archivo?

300 MB. Meta escribe "File size: 300MB maximum" para los reels, y la cifra es específica de los reels: un vídeo de story está limitado a "100MB maximum" y una imagen a "8 MB maximum" en esa misma página.

Si tu archivo de origen es grande o tu conexión poco fiable, Meta ofrece una segunda vía de subida en lugar de un tope mayor. Poner upload_type=resumable en la llamada del contenedor devuelve tanto un id como un uri, y luego empujas los bytes a rupload.facebook.com con las cabeceras offset y file_size:

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
     -H "Authorization: OAuth <ACCESS_TOKEN>" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Meta describe la sesión reanudable como pensada para "large videos from an area with frequent network interruptions or other transmission failures," y la restringe a las apps que han implementado el Facebook Login for Business. El techo de 300 MB sigue aplicándose.

¿Qué contenedor y qué códecs funcionan?

Solo MOV o MP4, con vídeo H264 o HEVC y audio AAC. Dos cláusulas de la regla de contenedor de Meta causan más fallos que los nombres de los códecs.

La primera es "moov atom at the front of the file." El átomo moov guarda el índice que le dice al reproductor dónde está todo lo demás. Los codificadores lo escriben al final por defecto porque los tamaños no se conocen hasta que termina la codificación. Moverlo al principio es lo que FFmpeg llama -movflags +faststart, y sin eso Meta tiene que leer el archivo entero antes de poder empezar, lo que es una fuente habitual del error de tiempo de descarga agotado en lugar de un error de formato.

La segunda es "no edit lists." Una lista de edición es una tabla de correspondencia que dice qué partes de una pista reproducir y cuándo. Las herramientas de recorte suelen dejar una en vez de recodificar. El archivo se reproduce bien en cualquier reproductor de escritorio y aquí se rechaza.

El resto de la regla de vídeo, "progressive scan, closed GOP, 4:2:0 chroma subsampling," descarta el material entrelazado y las codificaciones con GOP abierto. Una exportación H264 estándar a 4:2:0 cumple las tres sin que tengas que hacer nada.

¿Qué frecuencia de fotogramas y qué relación de aspecto exige Meta?

La frecuencia de fotogramas tiene que quedar entre 23 y 60 FPS. Meta escribe "Frame rate: 23-60 FPS," lo que excluye la salida a 15 FPS que producen por defecto los grabadores de pantalla y varias herramientas de vídeo con IA, y excluye los 120 FPS que graba un móvil en modo cámara lenta.

La relación de aspecto es donde los propios números de Meta se ponen raros. La regla de Reels es "Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space." Una relación de 0.01:1 es un vídeo cien veces más alto que ancho. Las Story Video Specifications, justo debajo y describiendo la misma canalización de transcodificación, fijan ese mismo límite en "between 0.1:1 and 10:1." Las dos cifras se diferencian en un factor de diez y las dos están vigentes en la misma página.

Ninguno de los dos límites es una regla de diseño. La regla de diseño es 9:16, y el ancho máximo de 1920 píxeles es lo que topa la resolución en la práctica. Nuestra nota sobre las dimensiones del vídeo vertical cubre de dónde sale 1080 por 1920, y la pieza sobre el tamaño de imagen de Instagram cubre el rango aparte de 4:5 a 1.91:1 que gobierna las fotos del feed.

¿Qué error devuelve cada incumplimiento?

Meta publica una tabla de subcódigos para la API de Instagram, y cruzarla con las especificaciones de reels deja al descubierto un hueco. Algunos incumplimientos tienen error propio. Varios no.

La duración no está en esa tabla. Tampoco el tamaño de archivo, la frecuencia de fotogramas ni la relación de aspecto de los reels. Meta documenta un subcódigo de relación de aspecto, 2207009, pero su propia solución recomendada describe imágenes: "Advise the app user to try again with an image that falls withing a 4:5 to 1.91:1 range." No hay equivalente listado para reels.

El propio puntero de la tabla también está roto. El arreglo de Meta para 2207026 dice "Advise the app user to upload an MOV or MP4 (MPEG-4 Part 14). See Video Specifications," y el enlace aterriza en un ancla #video-specifications de la referencia de IG User Media. Esa página ahora lleva Image Specifications, Reel Specifications, Story Image Specifications y Story Video Specifications. No hay ninguna sección Video Specifications donde aterrizar.

La consecuencia práctica: un reel demasiado largo o demasiado pesado sale casi siempre como 2207053, el error de subida desconocido, cuyo remedio documentado es "Generate a new container and use it to try again." Ese es un mensaje poco útil para un archivo que nunca iba a ser aceptado, y es el argumento para validar duración y tamaño en local antes de llamar a POST /<IG_ID>/media.

¿Cómo sabes que un reel ha pasado?

Consulta el contenedor. La referencia de Meta es explícita en que "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful," y en que lo confirmas pidiendo status_code y esperando a FINISHED. El conjunto completo de valores y la cadencia de sondeo que recomienda Meta están en el análisis del status_code del contenedor de Instagram. Si estás cableando el flujo entero en lugar de depurar un archivo, el recorrido sobre cómo programar reels de Instagram cubre las llamadas de alrededor.

Preguntas frecuentes

¿Cuál es la duración máxima de un reel a través de la API?

Quince minutos. Las Reel Specifications de Meta dicen "Duration: 15 mins maximum, 3 seconds minimum."

¿Cuál es el tamaño máximo de archivo de un reel?

300 MB. Los vídeos de story están limitados por debajo, a 100 MB, en esa misma referencia.

¿La API acepta WebM o AVI?

No. Meta lista únicamente MOV y MP4, y devuelve el subcódigo 2207026 con el mensaje The video format is not supported para cualquier otra cosa.

¿Puede aparecer un reel dentro de un carrusel?

No. Las limitaciones de reels de Meta indican "Reels cannot appear in carousels."

¿Qué relación de aspecto debería usar un reel?

9:16. El rango que acepta Meta es mucho más amplio, "between 0.01:1 and 10:1," pero esa misma frase recomienda 9:16 "to avoid cropping or blank space."

¿Un reel necesita imagen de portada?

No. Puedes pasar cover_url o thumb_offset, y Meta deja thumb_offset en 0 por defecto, el primer fotograma. Si envías los dos, Meta usa cover_url e ignora thumb_offset.

¿Qué ocurre si un reel se recorta a menos de tres segundos?

Meta lo rechaza directamente. Las Reel Specifications fijan un mínimo de 3 segundos, y no hay margen ni relleno automático por parte de Meta. Un clip que funciona sin problema en cualquier otro rincón de internet falla aquí solo por su duración.

¿Por qué un reel demasiado grande devuelve "unknown upload error" en lugar de un mensaje claro?

La tabla de subcódigos de Meta no tiene una entrada dedicada para infracciones de duración o de tamaño de archivo. Un reel demasiado largo o demasiado pesado suele aparecer como el subcódigo 2207053, cuyo único remedio documentado es generar un nuevo contenedor y volver a intentarlo. Eso no soluciona nada en un archivo que nunca iba a ser aceptado, por eso conviene comprobar la duración y el tamaño en local antes de llamar a la API.

¿Cómo se compara el límite de tamaño de archivo de un reel con el de una historia o una imagen?

Un reel puede pesar hasta 300 MB. Un vídeo de historia está limitado a 100 MB y una imagen a 8 MB, los tres en la misma página de la IG User Media Reference. El límite de los reels triplica al de las historias.

¿Por qué la API rechaza un vídeo que se reproduce sin problemas en un ordenador?

Dos detalles del contenedor provocan la mayoría de estos fallos. Una edit list dejada por un programa de edición, o un átomo moov escrito al final del archivo en lugar de al principio, se reproducen bien en cualquier reproductor de escritorio pero fallan o provocan un tiempo de espera agotado frente a la referencia de Meta. Volver a exportar con el átomo moov al principio, la opción -movflags +faststart de FFmpeg, y sin edit list resuelve ambos problemas.