Todos os limites que a API de Reels do Instagram impõe ao seu vídeo

O que a API de Reels do Instagram aceita?

Um vídeo empurrado pela API de Reels do Instagram tem que passar por cada linha de um bloco de especificação publicado antes de a Meta transcodificá-lo, e esse bloco fica num lugar só: Reel Specifications, na referência IG User Media. Erre uma linha e o contêiner que você criou com media_type=REELS volta com status_code em ERROR no lugar de FINISHED.

Aqui está a lista inteira, copiada da referência da Meta.

Quanto tempo um reel pode ter pela API?

Quinze minutos. A linha da Meta é "Duration: 15 mins maximum, 3 seconds minimum," o que deixa o teto da API bem mais alto do que a maioria espera e o piso mais alto do que a maioria percebe.

O mínimo de três segundos é o que morde. Um clipe cortado em dois segundos e meio é um ativo perfeitamente comum em qualquer outro canto da internet e uma rejeição imediata aqui. Não há crédito parcial nem preenchimento aplicado do lado da Meta.

O teto de quinze minutos merece uma ressalva que a Meta não anexa a ele. Esse número governa o que a API aceita dentro de um contêiner. Não diz nada sobre o que o app do Instagram deixa uma pessoa subir pelo celular, nem sobre o que o sistema de recomendação vai fazer com um reel de catorze minutos depois que ele existir. A Meta anexa exatamente esse tipo de aviso ao parâmetro share_to_feed, notando que nenhum 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." A API aceitar um arquivo e o Instagram distribuí-lo são duas perguntas diferentes.

Qual o tamanho máximo do arquivo?

300 MB. A Meta escreve "File size: 300MB maximum" para reels, e a cifra é específica de reels: um vídeo de story para em "100MB maximum" e uma imagem em "8 MB maximum" na mesma página.

Se o seu arquivo de origem é grande ou a sua conexão não é confiável, a Meta oferece um segundo caminho de upload em vez de um teto maior. Definir upload_type=resumable na chamada de criação do contêiner devolve tanto um id quanto um uri, e você então empurra os bytes para rupload.facebook.com com os cabeçalhos offset e 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"

A Meta descreve a sessão retomável como sendo para "large videos from an area with frequent network interruptions or other transmission failures," e a restringe a apps que implementaram o Facebook Login for Business. O teto de 300 MB continua valendo.

Quais contêineres e codecs funcionam?

Só MOV ou MP4, com vídeo H264 ou HEVC e áudio AAC. Duas cláusulas da regra de contêiner da Meta causam mais falhas do que os nomes dos codecs.

A primeira é "moov atom at the front of the file." O átomo moov guarda o índice que diz ao player onde todo o resto mora. Codificadores o escrevem no fim por padrão, porque os tamanhos só são conhecidos quando a codificação termina. Movê-lo para a frente é o que o FFmpeg chama de -movflags +faststart, e sem isso a Meta tem que ler o arquivo inteiro antes de começar, o que é fonte comum do erro de timeout de download em vez de um erro de formato.

A segunda é "no edit lists." Uma edit list é uma tabela de mapeamento que diz quais partes de uma trilha tocar e quando. Ferramentas de corte frequentemente deixam uma para trás em vez de recodificar. O arquivo toca certinho em todo player de desktop e é rejeitado aqui.

O resto da regra de vídeo, "progressive scan, closed GOP, 4:2:0 chroma subsampling," descarta footage entrelaçado e codificações com GOP aberto. Uma exportação H264 padrão em 4:2:0 satisfaz as três sem você fazer nada.

Que taxa de quadros e proporção a Meta exige?

A taxa de quadros tem que ficar entre 23 e 60 FPS. A Meta escreve "Frame rate: 23-60 FPS," o que exclui a saída de 15 FPS que gravadores de tela e várias ferramentas de vídeo com IA produzem por padrão, e exclui os 120 FPS que um celular grava em câmera lenta.

A proporção é onde os próprios números da Meta ficam estranhos. A regra de Reels é "Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16 to avoid cropping or blank space." Uma proporção de 0.01:1 é um vídeo cem vezes mais alto do que largo. As Story Video Specifications logo abaixo, descrevendo o mesmo pipeline de transcodificação, fixam o mesmo limite em "between 0.1:1 and 10:1." Os dois números diferem por um fator de dez e os dois estão no ar na mesma página.

Nenhum dos dois limites é regra de design. 9:16 é a regra de design, e o máximo de 1920 pixels de largura é o que limita a resolução na prática. Nossa nota sobre dimensões de vídeo vertical cobre de onde vem 1080 por 1920, e o texto sobre tamanho de imagem do Instagram cobre o intervalo separado de 4:5 a 1.91:1 que governa fotos de feed.

Que erro cada violação devolve?

A Meta publica uma tabela de subcódigos para a API do Instagram, e cruzá-la com as specs de reels expõe uma lacuna. Algumas violações têm erro dedicado. Várias não têm.

Duração não está nessa tabela. Nem tamanho de arquivo, nem taxa de quadros, nem proporção de reels. A Meta documenta um subcódigo de proporção, o 2207009, mas sua própria solução recomendada descreve imagens: "Advise the app user to try again with an image that falls withing a 4:5 to 1.91:1 range." Não há equivalente listado para reels.

O próprio ponteiro da tabela também está quebrado. O conserto da Meta para o 2207026 diz "Advise the app user to upload an MOV or MP4 (MPEG-4 Part 14). See Video Specifications," e o link cai numa âncora #video-specifications da referência IG User Media. Aquela página hoje carrega Image Specifications, Reel Specifications, Story Image Specifications e Story Video Specifications. Não existe seção Video Specifications onde cair.

A consequência prática: um reel longo demais ou grande demais na maioria das vezes aparece como 2207053, o erro de upload desconhecido, cujo remédio documentado é "Generate a new container and use it to try again." É uma mensagem inútil para um arquivo que nunca seria aceito, e é o argumento para validar duração e tamanho localmente antes de chamar o POST /<IG_ID>/media.

Como saber que um reel passou?

Consultando o contêiner. A referência da Meta é explícita ao dizer que "Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful," e que você confirma pedindo o status_code e esperando o FINISHED. O conjunto completo de valores e a cadência de polling que a Meta recomenda estão no texto sobre o status_code do contêiner do Instagram. Se você está ligando o fluxo inteiro em vez de depurar um arquivo, o passo a passo sobre agendar reels do Instagram cobre as chamadas em volta.

Perguntas frequentes

Qual a duração máxima de um reel pela API?

Quinze minutos. As Reel Specifications da Meta dizem "Duration: 15 mins maximum, 3 seconds minimum."

Qual o tamanho máximo de arquivo de um reel?

300 MB. Vídeos de story param mais baixo, em 100 MB, na mesma referência.

A API aceita WebM ou AVI?

Não. A Meta lista só MOV e MP4, e devolve o subcódigo 2207026 com a mensagem The video format is not supported para qualquer outra coisa.

Um reel pode aparecer em um carrossel?

Não. As limitações de reels da Meta afirmam "Reels cannot appear in carousels."

Que proporção um reel deve usar?

9:16. O intervalo aceito pela própria Meta é bem mais largo, "between 0.01:1 and 10:1," mas a mesma frase recomenda 9:16 "to avoid cropping or blank space."

Um reel precisa de imagem de capa?

Não. Você pode passar cover_url ou thumb_offset, e a Meta usa 0 como padrão de thumb_offset, o primeiro quadro. Se os dois forem enviados, a Meta usa cover_url e ignora thumb_offset.

O que acontece se um reel for cortado para menos de três segundos?

A Meta rejeita na hora. As Reel Specifications definem um mínimo de 3 segundos, sem nenhuma margem ou preenchimento automático por parte da Meta. Um clipe que funciona bem em qualquer outro lugar da internet falha aqui só por causa da duração.

Por que um reel grande demais retorna "unknown upload error" em vez de uma mensagem clara?

A tabela de subcódigos da Meta não tem uma entrada dedicada para violações de duração ou tamanho de arquivo. Um reel longo ou pesado demais costuma aparecer como o subcódigo 2207053, cujo único remédio documentado é gerar um novo contêiner e tentar de novo. Isso não resolve nada para um arquivo que nunca seria aceito, e é por isso que vale checar duração e tamanho localmente antes de chamar a API.

Como o limite de tamanho de arquivo de um reel se compara ao de um story ou de uma imagem?

Um reel pode pesar até 300 MB. Um vídeo de story é limitado a 100 MB e uma imagem a 8 MB, os três na mesma página da IG User Media Reference. O limite dos reels é o triplo do limite dos stories.

Por que um vídeo que roda sem problemas no computador é rejeitado pela API?

Dois detalhes do contêiner causam a maioria dessas falhas. Uma edit list deixada por um programa de edição, ou um átomo moov escrito no fim do arquivo em vez do início, tocam normalmente em qualquer player de desktop mas falham ou expiram diante da referência da Meta. Reexportar com o átomo moov movido para o início, a opção -movflags +faststart do FFmpeg, e sem edit list resolve os dois problemas.