Los requisitos de imagen de la API de Instagram que Meta aplica al subir

¿Cuáles son los requisitos de imagen de la API de Instagram?

Cuatro reglas forman los requisitos de imagen de la API de Instagram, y Meta imprime las cuatro en un mismo bloque bajo "Image Specifications" en la referencia de POST /<IG_ID>/media: formato JPEG, 8 MB de tamaño máximo de archivo, una relación de aspecto dentro del rango de 4:5 a 1.91:1 y un ancho de entre 320 y 1440 píxeles. Citadas tal y como las publica Meta:

Format: JPEG

File size: 8 MB maximum.

Aspect ratio: Must be within a 4:5 to 1.91:1 range

Minimum width: 320 (will be scaled up to the minimum if necessary)

Maximum width: 1440 (will be scaled down to the maximum if necessary)

Height: Varies, depending on width and aspect ratio

Color Space: sRGB. Images using other color spaces will have their color spaces converted to sRGB.

La guía de publicación de contenido repite la regla de formato en un lenguaje más seco bajo su propio apartado de Limitations: "JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported."

Lee el bloque otra vez y aparece una división. Dos de estas reglas rechazan la petición. Otras dos reescriben tu archivo sin decir nada. Formato, tamaño de archivo y relación de aspecto son comprobaciones, y el fallo vuelve como un HTTP 400 con un código y un subcódigo. Ancho y espacio de color son conversiones, y Meta lo dice dentro de los paréntesis: escalada hacia arriba, escalada hacia abajo, convertida a sRGB. Nada te avisa de que ha ocurrido.

Esa distinción decide cómo validas antes de llamar a la API. Al primer grupo lo cazas leyendo el error. Al segundo solo lo cazas midiendo el archivo tú mismo.

¿Qué código de error devuelve cada infracción?

Todo fallo de imagen que Meta documenta llega como estado HTTP 400 con un objeto JSON error que lleva code, error_subcode, error_user_title y error_user_msg. La referencia de códigos de error de Instagram los mapea uno a uno.

El error de ejemplo que Meta imprime en lo alto de esa referencia es el del tamaño de archivo, y merece copiarse literalmente porque la redacción difiere de la hoja de especificaciones:

{
  "error": {
    "message": "The image size is too large.",
    "type": "OAuthException",
    "code": 36000,
    "error_subcode": 2207004,
    "is_transient": false,
    "error_user_title": "Image size too large",
    "error_user_msg": "The image is too large to download. It should be less than 8 MiB.",
    "fbtrace_id": "A6LJylpZRKw2xKLFsAP-cJh"
  }
}

Una fila de esa tabla arrastra un error en la propia documentación de Meta. La columna Recommended Solution para 36001 subcódigo 2207005, el rechazo por formato, dice "Possible permission error due to missing permission or expired token. Generate a new container and use it to try again." Ese es el texto de solución del código 24 subcódigo 2207006, un fallo completamente distinto, pegado en la fila del formato. Un PNG no se convierte en JPEG cuando refrescas un token. Ignora la columna de solución en esa fila y lee el mensaje de usuario.

¿El límite son 8 MB u 8 MiB?

Meta publica ambas cifras en dos páginas vivas. La referencia de medios dice "File size: 8 MB maximum." La referencia de códigos de error dice que la imagen "should be less than 8 MiB" en la respuesta de ejemplo, y la columna Recommended Solution de esa misma fila dice "Image exceeded maximum file size of 8MiB."

No son el mismo techo. 8 MB son 8.000.000 de bytes. 8 MiB son 8.388.608 bytes. La diferencia entre ambos es de 388.608 bytes, una banda de aproximadamente un tercio de megabyte donde la hoja de especificaciones dice no y el texto del error dice sí.

Construye contra 8.000.000 de bytes. El menor de dos límites publicados es el que no puede sorprenderte, y el margen que cedes es pequeño al lado de una publicación que falla en el paso del contenedor. Si comprimes al entrar, apunta bastante por debajo: un JPEG que aterriza en 6 MB sobrevive a una recodificación en el lado de Meta sin acercarse a ninguna de las dos cifras. El mismo hábito defensivo se aplica a el techo de 2.200 caracteres del caption y su subregla de 20 etiquetas @, donde el campo se comprueba al crear el contenedor y no al publicar.

¿Qué pasa cuando la imagen es demasiado ancha o demasiado estrecha?

Nada que puedas cazar en la respuesta. Meta remuestrea el archivo y sigue adelante.

El ancho mínimo son 320 píxeles y el máximo 1440, y las dos líneas terminan con la misma promesa: la imagen "will be scaled up to the minimum if necessary" y "will be scaled down to the maximum if necessary." No existe código de error en ninguna de las dos direcciones. Una fotografía de 4000 píxeles de ancho se acepta, se remuestrea a 1440 y se publica con una resolución que tú no elegiste. Una miniatura de 200 píxeles se acepta, se estira hasta 320 y se publica blanda.

La altura no es una cifra fija en ningún punto de la especificación. Meta escribe "Height: Varies, depending on width and aspect ratio", lo que significa que la altura es una consecuencia de las dos reglas que sí se aplican, no una regla propia. Fija el ancho en 1440 y la relación de aspecto en 4:5 y la altura sale en 1800 píxeles, el encuadre más alto que acepta el endpoint del feed.

El espacio de color se comporta igual. Todo lo que no sea sRGB se convierte, sin aviso y sin error. Una exportación en Display P3 desde un teléfono o un editor de fotos se publica bien y se publica más apagada de lo que se veía en tu pantalla. Convierte a sRGB antes de subir para que la conversión sea una que controlaste tú. El mismo principio guía las dimensiones en píxeles que aguantan en todas las superficies de Instagram: elige el tamaño que Meta no va a tocar.

¿En qué se diferencian las reglas de la API de lo que acepta la app de Instagram?

Meta le da a la app un juego de cifras distinto en una página distinta. El artículo del Centro de ayuda de Instagram "Image resolution of photos you share on Instagram" le dice a la gente que "Upload a photo with a width of at least 1080 pixels with an aspect ratio between 1.91:1 and 3:4."

Ponlos uno al lado del otro.

El borde alto es el que muerde. 4:5 es 0,8. 3:4 es 0,75. Un recorte vertical 3:4 que la app acepta sin quejarse vuelve de la API como código 36003, subcódigo 2207009, porque cae fuera del rango documentado. Quien lleva un flujo de trabajo de teléfono a un flujo de trabajo de API choca primero con esto.

Las reglas de ancho se detienen en puntos distintos. Los dos documentos arrancan en 320, y el Centro de ayuda dice que una foto más estrecha se amplía hasta 320. Por encima de ahí divergen: la API baja a 1440 todo lo que pase de 1440, mientras que la app baja a 1080 todo lo que pase de 1080. Exporta a 1080 píxeles de ancho y ninguno de los dos documentos tiene motivo para tocar el archivo. AdaptlyPost publica en Instagram a través de esta API, así que el mismo techo se aplica a todo lo programado en lugar de publicado a mano.

Otras dos funciones de la app están ausentes de la API por diseño. La guía de publicación de contenido dice sin rodeos que "Shopping tags are not supported" y "Filters are not supported." Ninguna devuelve un error útil, porque ninguno de los dos parámetros existe.

¿Qué reglas cambian para historias, portadas de reels y carruseles?

El techo de 8 MB y la regla del JPEG valen en todas partes. La regla de la relación de aspecto no.

Las historias abandonan por completo el rango obligatorio. Meta solo escribe que "recommended 9:16 to avoid cropping or blank space", lo que significa que una imagen cuadrada se publica como historia con bandas y no como error.

Las portadas de reels recortan dos veces. Meta dice que si la portada no es 9:16, "we crop the image and use the middle most 9:16 rectangle as the cover photo for the reel", y que compartir el reel en el feed dispara un segundo recorte, "the middle most 1:1 square." Cualquier cosa importante cerca de un borde ha desaparecido cuando llega a la cuadrícula.

Los carruseles ignoran la relación de aspecto de todas las diapositivas menos la primera. La guía es explícita: "Carousel images are all cropped based on the first image in the carousel, with the default being a 1:1 aspect ratio." Ordena tus hijos a conciencia, porque la diapositiva uno fija el encuadre de las diez. Esa restricción convive con el recuento de contenedores y la cuota de publicación que gobiernan un carrusel, donde un carrusel de diez imágenes sigue gastando una publicación. Y si pones texto alternativo en la misma petición, el campo alt_text lleva su propio techo aparte, que no tiene nada que ver con la imagen en sí.

Preguntas frecuentes

¿La API de Instagram acepta imágenes PNG?

No. Meta escribe "JPEG is the only image format supported" en la guía de publicación de contenido. Un PNG devuelve el código 36001, subcódigo 2207005, con el mensaje "The image format {current-image-format} is not supported. Supported formats are: {format}."

¿Cuál es el tamaño máximo de archivo de imagen en la API de Instagram?

Meta publica dos cifras. La referencia de medios dice "File size: 8 MB maximum." La referencia de códigos de error dice que la imagen "should be less than 8 MiB", que son 8.388.608 bytes. Construye contra la cifra menor, 8.000.000 de bytes.

¿Qué relaciones de aspecto rechaza la API de Instagram?

Cualquiera fuera del rango de 4:5 a 1.91:1. Eso rechaza 3:4, 9:16 y 2:1 en imágenes de feed, y devuelve el código 36003, subcódigo 2207009.

¿Una imagen de 4000 píxeles de ancho falla en la API de Instagram?

No. Meta la escala hasta el máximo de 1440 píxeles y la publica. No existe código de error para un ancho fuera de rango en ninguna dirección.

¿Se aceptan los archivos MPO y JPS como JPEG?

No. La guía de publicación de contenido los nombra directamente: "Extended JPEG formats such as MPO and JPS are not supported."

¿Las imágenes de historias y carruseles siguen la misma regla de relación de aspecto que las publicaciones de feed?

No. Las historias no tienen rango obligatorio publicado, solo una recomendación de 9:16. Las diapositivas de carrusel se recortan para coincidir con la primera imagen del carrusel, con 1:1 por defecto.

¿A qué altura publica una imagen la API de Instagram?

Meta no fija un número de altura en la especificación, solo escribe "Height: Varies, depending on width and aspect ratio". La altura resulta de las dos reglas que sí se aplican, el ancho y la relación de aspecto, en lugar de ser una regla propia. Si el ancho llega al máximo de 1440 píxeles y la relación de aspecto es 4:5, la imagen se publica con 1800 píxeles de alto, el marco más alto que acepta el endpoint del feed.

¿Se puede confiar en la columna Recommended Solution de la referencia de códigos de error de Meta?

No en todas las filas. El texto junto al código 36001, el rechazo de formato, describe en realidad el código 24, un error de permisos, y sugiere generar un nuevo contenedor y volver a intentarlo. Un PNG no se convierte en JPEG por renovar un token, así que en esa fila conviene leer el campo error_user_msg en vez de la columna de solución.

¿Una foto de portada de reel se recorta más de una vez?

Puede recortarse dos veces. Meta recorta primero cualquier portada que no sea 9:16 al rectángulo 9:16 más central, y la recorta una segunda vez al cuadrado 1:1 más central si el reel también se comparte en el feed. Lo que queda cerca del borde de la imagen original desaparece antes de llegar a la cuadrícula.

¿La app de Instagram impone un límite de tamaño de archivo igual que la API?

El artículo del Help Center sobre resolución de fotos no publica ninguna cifra de tamaño de archivo. Solo la Graph API documenta una, 8 MB en la especificación y 8 MiB en el texto del error, así que el límite de tamaño de archivo es una regla exclusiva de la API sin equivalente publicado en la app.