Os requisitos de imagem da Instagram API que a Meta aplica no upload

Quais são os requisitos de imagem da Instagram API?

Quatro regras formam os requisitos de imagem da Instagram API, e a Meta imprime as quatro em um bloco só, sob "Image Specifications", na referência do POST /<IG_ID>/media: formato JPEG, tamanho máximo de arquivo de 8 MB, proporção dentro de uma faixa de 4:5 a 1.91:1 e largura entre 320 e 1440 pixels. Citadas como a Meta as publica:

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.

O guia de Content Publishing repete a regra de formato em linguagem mais crua sob o próprio título Limitations: "JPEG is the only image format supported. Extended JPEG formats such as MPO and JPS are not supported."

Leia o bloco de novo e uma divisão aparece. Duas dessas regras rejeitam a requisição. Duas delas reescrevem o seu arquivo em silêncio. Formato, tamanho de arquivo e proporção são verificações, e uma falha volta como um HTTP 400 com código e subcódigo. Largura e espaço de cor são conversões, e a Meta diz isso entre parênteses: ampliada, reduzida, convertida para sRGB. Nada avisa que aconteceu.

Essa distinção decide como você valida antes de chamar a API. O primeiro grupo você pega lendo o erro. O segundo grupo você só pega medindo o arquivo por conta própria.

Qual código de erro cada violação devolve?

Toda falha de imagem que a Meta documenta chega como status HTTP 400 com um objeto JSON error carregando code, error_subcode, error_user_title e error_user_msg. A referência de códigos de erro do Instagram mapeia uma para uma.

O erro de exemplo que a Meta imprime no topo dessa referência é o de tamanho de arquivo, e vale copiar literalmente porque a redação difere da ficha de especificação:

{
  "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"
  }
}

Uma linha dessa tabela carrega um engano na documentação da própria Meta. A coluna Recommended Solution para 36001 subcódigo 2207005, a rejeição de formato, diz "Possible permission error due to missing permission or expired token. Generate a new container and use it to try again." Esse é o texto de solução do código 24 subcódigo 2207006, uma falha completamente diferente, colado na linha de formato. Um PNG não vira JPEG quando você renova um token. Ignore a coluna de solução nessa linha e leia a mensagem de usuário.

O limite é 8 MB ou 8 MiB?

A Meta publica os dois números em duas páginas ativas. A referência de mídia diz "File size: 8 MB maximum." A referência de códigos de erro diz que a imagem "should be less than 8 MiB" na resposta de exemplo, e a coluna Recommended Solution da mesma linha diz "Image exceeded maximum file size of 8MiB."

Esses tetos não são o mesmo. 8 MB são 8.000.000 de bytes. 8 MiB são 8.388.608 bytes. A diferença entre eles é de 388.608 bytes, uma faixa de cerca de um terço de megabyte onde a ficha de especificação diz não e o texto do erro diz sim.

Construa contra 8.000.000 de bytes. O menor de dois limites publicados é o que não tem como te surpreender, e a margem que você abre mão é pequena perto de uma publicação que falha na etapa do container. Se você comprime na entrada, mire bem abaixo disso: um JPEG que fecha em 6 MB sobrevive a uma recodificação do lado da Meta sem chegar perto de nenhum dos dois números. O mesmo hábito defensivo vale para o teto de 2.200 caracteres na legenda e a subregra das 20 marcações @, onde o campo é verificado na criação do container e não na publicação.

O que acontece quando a imagem é larga ou estreita demais?

Nada que você consiga pegar na resposta. A Meta reamostra o arquivo e segue em frente.

A largura mínima é 320 pixels e a máxima é 1440, e as duas linhas terminam com a mesma promessa: a imagem "will be scaled up to the minimum if necessary" e "will be scaled down to the maximum if necessary." Não existe código de erro para nenhuma das duas direções. Uma fotografia de 4000 pixels de largura é aceita, reamostrada para 1440 e publicada em uma resolução que você não escolheu. Uma miniatura de 200 pixels é aceita, esticada para 320 e publicada borrada.

Altura não é número fixo em lugar nenhum da especificação. A Meta escreve "Height: Varies, depending on width and aspect ratio", o que significa que a altura é consequência das duas regras que são aplicadas, não uma regra própria. Fixe a largura em 1440 e a proporção em 4:5 e a altura sai em 1800 pixels, o quadro mais alto que o endpoint de feed aceita.

O espaço de cor se comporta do mesmo jeito. Qualquer coisa que não seja sRGB é convertida, sem aviso e sem erro. Uma exportação em Display P3 vinda de um celular ou de um editor de fotos publica normalmente e publica mais sem graça do que parecia na sua tela. Converta para sRGB antes do upload para que a conversão seja uma que você controlou. O mesmo princípio guia as dimensões em pixels que se sustentam nas superfícies do Instagram: escolha o tamanho em que a Meta não vai encostar.

Como as regras da API diferem do que o app do Instagram aceita?

A Meta dá ao app um conjunto de números diferente em uma página diferente. O artigo da Central de Ajuda do Instagram "Image resolution of photos you share on Instagram" diz às pessoas para "Upload a photo with a width of at least 1080 pixels with an aspect ratio between 1.91:1 and 3:4."

Coloque os dois lado a lado.

A borda alta é a que morde. 4:5 é 0,8. 3:4 é 0,75. Um recorte retrato em 3:4 que o app aceita sem reclamar volta da API como código 36003, subcódigo 2207009, porque cai fora da faixa documentada. Quem migra um fluxo de celular para um fluxo de API bate nisso primeiro.

As regras de largura param em pontos diferentes. Os dois documentos começam em 320, e a Central de Ajuda diz que uma foto mais estreita que isso é ampliada para 320. Acima disso eles divergem: a API reduz para 1440 tudo o que passa de 1440, enquanto o app reduz para 1080 tudo o que passa de 1080. Exporte com 1080 pixels de largura e nenhum dos dois documentos tem motivo para mexer no arquivo. A AdaptlyPost publica no Instagram por essa API, então o mesmo teto vale para qualquer coisa agendada em vez de postada na mão.

Dois recursos do app estão ausentes da API por projeto. O guia de Content Publishing afirma claramente que "Shopping tags are not supported" e "Filters are not supported." Nenhum dos dois devolve erro útil, porque nenhum dos dois parâmetros existe.

Quais regras mudam para stories, capas de reels e carrosséis?

O teto de 8 MB e a regra do JPEG valem em todo lugar. A regra de proporção não.

Stories abandonam a faixa aplicada por completo. A Meta escreve apenas que é "recommended 9:16 to avoid cropping or blank space", o que significa que uma imagem quadrada publica como story com barras em vez de erro.

Capas de reels são recortadas duas vezes. A Meta diz que, se a capa não for 9:16, "we crop the image and use the middle most 9:16 rectangle as the cover photo for the reel", e que compartilhar o reel no feed dispara um segundo recorte, "the middle most 1:1 square." O que for importante perto de uma borda já sumiu quando a imagem chega à grade.

Carrosséis ignoram a proporção de todos os slides menos o primeiro. O guia é explícito: "Carousel images are all cropped based on the first image in the carousel, with the default being a 1:1 aspect ratio." Ordene os filhos de propósito, porque o slide um define o quadro dos dez. Essa restrição anda junto com a contagem de containers e a cota de publicação que governam um carrossel, onde um carrossel de dez imagens ainda gasta uma publicação. E se você define texto alternativo na mesma requisição, o campo alt_text carrega o próprio teto separado, que não tem nada a ver com a imagem em si.

Perguntas frequentes

A Instagram API aceita imagens PNG?

Não. A Meta escreve "JPEG is the only image format supported" no guia de Content Publishing. Um PNG devolve o código 36001, subcódigo 2207005, com a mensagem "The image format {current-image-format} is not supported. Supported formats are: {format}."

Qual é o tamanho máximo de arquivo de imagem na Instagram API?

A Meta publica duas cifras. A referência de mídia diz "File size: 8 MB maximum." A referência de códigos de erro diz que a imagem "should be less than 8 MiB", ou seja, 8.388.608 bytes. Construa contra o número menor, 8.000.000 de bytes.

Quais proporções a Instagram API rejeita?

Qualquer uma fora da faixa de 4:5 a 1.91:1. Isso rejeita 3:4, 9:16 e 2:1 em imagens de feed, e devolve o código 36003, subcódigo 2207009.

Uma imagem de 4000 pixels de largura falha na Instagram API?

Não. A Meta reduz para o máximo de 1440 pixels e publica. Não existe código de erro para largura fora da faixa em nenhuma das duas direções.

Arquivos MPO e JPS são aceitos como JPEG?

Não. O guia de Content Publishing os nomeia diretamente: "Extended JPEG formats such as MPO and JPS are not supported."

Imagens de story e de carrossel seguem a mesma regra de proporção dos posts de feed?

Não. Stories não têm faixa aplicada publicada, apenas uma recomendação de 9:16. Slides de carrossel são recortados para casar com a primeira imagem do carrossel, tendo 1:1 como padrão.

Com que altura uma imagem é publicada pela Instagram API?

Meta não fixa um número de altura na especificação, o texto diz apenas "Height: Varies, depending on width and aspect ratio". A altura resulta das duas regras que de fato são aplicadas, a largura e a proporção, em vez de ser uma regra própria. Se a largura chega ao máximo de 1440 pixels e a proporção é 4:5, a imagem é publicada com 1800 pixels de altura, o quadro mais alto que o endpoint do feed aceita.

Dá para confiar na coluna Recommended Solution da referência de códigos de erro do Meta?

Não em todas as linhas. O texto ao lado do código 36001, a rejeição de formato, na verdade descreve o código 24, um erro de permissão, e sugere gerar um novo container e tentar de novo. Um PNG não vira JPEG só porque um token foi renovado, por isso vale ler o campo error_user_msg em vez da coluna de solução nessa linha.

Uma foto de capa de reel é cortada mais de uma vez?

Ela pode ser cortada duas vezes. O Meta corta primeiro qualquer capa que não esteja em 9:16 para o retângulo 9:16 mais central, e corta uma segunda vez para o quadrado 1:1 mais central se o reel também for compartilhado no feed. O que fica perto da borda da imagem original some antes de chegar à grade.

O app do Instagram impõe um limite de tamanho de arquivo como a API?

O artigo do Central de Ajuda sobre resolução de fotos não publica nenhum número de tamanho de arquivo. Só a Graph API documenta um, 8 MB na especificação e 8 MiB no texto do erro, então o limite de tamanho de arquivo é uma regra exclusiva da API, sem equivalente publicado no app.