Publicar no Instagram através da API é uma chamada em dois passos: crie um container de mídia com POST /<IG_ID>/media, depois publique-o com POST /<IG_ID>/media_publish. As partes difíceis não são as chamadas. São os requisitos de conta, a revisão de aplicativo da Meta, e o fato de que uma resposta 200 no passo do container não significa que algo já está no ar.
Este texto é escrito para um desenvolvedor decidindo se deve construir isso internamente.
O que a API do Instagram consegue de fato publicar?
A documentação de Publicação de Conteúdo da Meta lista quatro valores de media_type para containers: VIDEO, REELS, STORIES e CAROUSEL. Uma imagem única simples é o padrão quando você passa image_url sem media_type.
| Formato | Suportado | Observações da documentação |
|---|---|---|
| Imagem única | Sim | JPEG, passada como um image_url público |
| Vídeo / Reels | Sim | media_type=REELS com video_url |
| Stories | Sim | media_type=STORIES |
| Carrossel | Sim | Até 10 imagens, vídeos ou uma mistura |
Duas coisas surpreendem as pessoas. Primeiro, Stories podem ser publicados, mas quando você lê um story publicado de volta, media_type retorna IMAGE ou VIDEO, então você precisa solicitar media_product_type para saber o que de fato é. Segundo, as imagens de um carrossel são todas cortadas para combinar com a primeira imagem, com padrão 1:1, então suas decisões de corte já vêm tomadas.
A lacuna que mais importa não é um formato. É a conta. A publicação exige uma conta profissional do Instagram (Empresarial ou Criador de Conteúdo) conectada a uma Página do Facebook, com instagram_basic, instagram_content_publish e pages_read_engagement concedidos. Uma conta pessoal do Instagram não pode receber publicações via API de forma alguma, não importa o que o seu código faça. Se seus usuários são criadores em contas pessoais, a integração está morta antes mesmo de você escrever uma linha.
Observação: os números aqui foram verificados na documentação de Publicação de Conteúdo da Plataforma Instagram da Meta em setembro de 2026. As plataformas mudam isso sem aviso prévio.
Como funciona a autenticação, e quanto tempo leva a revisão de aplicativo?
Você obtém um token de acesso de usuário através do Login com Facebook, depois troca o token de curta duração, no servidor, por um de longa duração via GET oauth/access_token com grant_type=fb_exchange_token. A Meta documenta o token de usuário de longa duração como tendo cerca de 60 dias de validade. A renovação automática que a Meta descreve se aplica a tokens gerenciados pelo SDK, então, se você troca os tokens por conta própria, precisa do seu próprio caminho de renovação ou reautenticação antes do dia 60.
A revisão de aplicativo é obrigatória para as permissões de publicação antes que qualquer pessoa fora das funções do seu próprio aplicativo possa usar a integração. A Meta não publica um prazo garantido de revisão nessa documentação para desenvolvedores, então trate a duração como desconhecida e planeje pelo menos uma rodada de rejeição. Gravações de tela fazem parte da submissão, o que significa que você precisa de uma demonstração funcional antes de obter aprovação, em um aplicativo que ainda não pode atender usuários reais.
Qual é a sequência de chamadas de publicação?
- Envie sua mídia para algum lugar publicamente acessível. A Meta busca a mídia pela URL, então uma URL assinada que expira em 60 segundos vai falhar.
POST /<IG_ID>/mediacomimage_urlouvideo_url,caption, emedia_typese não for uma imagem simples. Você recebe de volta um ID de container.- Consulte
GET /<IG_CONTAINER_ID>?fields=status_coderepetidamente até que retorneFINISHED. A Meta recomenda consultar uma vez por minuto por no máximo cinco minutos. POST /<IG_ID>/media_publishcomcreation_iddefinido como o ID do container.- Guarde o ID de mídia retornado. Esse, e não o ID do container, é a publicação publicada.
# 1. create the container
curl -X POST "https://graph.facebook.com/v23.0/$IG_ID/media" \
-d "image_url=https://example.com/photo.jpg" \
-d "caption=Ship it." \
-d "access_token=$TOKEN"
# -> {"id":"17889455560051444"}
# 2. poll until FINISHED
curl "https://graph.facebook.com/v23.0/17889455560051444?fields=status_code&access_token=$TOKEN"
# 3. publish
curl -X POST "https://graph.facebook.com/v23.0/$IG_ID/media_publish" \
-d "creation_id=17889455560051444" -d "access_token=$TOKEN"O status_code do container pode ser IN_PROGRESS, FINISHED, ERROR, EXPIRED ou PUBLISHED. EXPIRED significa que o container não foi publicado dentro de 24 horas. Para um carrossel, você cria um container por item com is_carousel_item=true, depois um container pai com media_type=CAROUSEL e uma lista children separada por vírgulas.
Quais são os limites de taxa?
O limite de publicação documentado é direto: contas do Instagram são limitadas a 100 publicações via API dentro de um período móvel de 24 horas, e um carrossel conta como uma publicação. Você pode ler o uso atual em GET /<IG_ID>/content_publishing_limit, em vez de adivinhar, o que você deveria fazer antes de uma execução em massa.
Essa é uma janela móvel, não um dia de calendário. Se você usar 100 publicações às 15h, você não recebe uma nova cota à meia-noite. Qualquer fila que você construir precisa modelar a janela, não um contador diário.
Observação: os números aqui foram verificados na documentação de Publicação de Conteúdo da Plataforma Instagram da Meta em setembro de 2026. As plataformas mudam isso sem aviso prévio.
O que de fato vai custar três semanas?
Não são as duas chamadas de API. São estas quatro coisas:
Revisão de aplicativo. Você não consegue lançar até a Meta aprovar instagram_content_publish, e não consegue demonstrar de forma limpa até ter construído a coisa. Reserve orçamento para reenvio.
Renovação de token. Tokens de longa duração de sessenta dias significam um processo em segundo plano, um estado de falha na sua interface para “esta conta precisa ser reconectada”, e um e-mail ao usuário antes de o token expirar, não depois. Pule isso e cada integração para de funcionar silenciosamente dois meses após o lançamento.
Hospedagem de mídia e restrições de formato. A Meta busca a mídia pela sua URL. Isso significa hospedagem pública, tipos de conteúdo corretos, e transcodificação para o que o Instagram aceita. Imagens únicas são JPEG. O vídeo precisa sobreviver à própria etapa de processamento do Instagram, que acontece depois que sua chamada retorna.
Tratamento de falha assíncrona. Um 200 na chamada do container significa que a Meta aceitou um trabalho. A publicação ainda pode falhar durante o processamento, e você só descobre consultando status_code e vendo ERROR. Se o seu modelo de dados só tem “publicado” e “falhou”, você vai reportar sucesso para publicações que nunca apareceram. Modele um estado processing e uma verificação terminal de verdade, como abordado no nosso guia de API de agendamento de redes sociais.
Depois multiplique. Reels e Stories têm suas próprias peculiaridades, e se você também quiser TikTok ou LinkedIn, você começa de novo com um modelo de autenticação diferente, um fluxo de upload diferente e um processo de revisão diferente.
Resumo rápido
- Duas chamadas: criar container, depois
media_publish. Consultestatus_codeentre uma e outra. - Exige uma conta profissional do Instagram vinculada a uma Página do Facebook.
- 100 publicações via API por período móvel de 24 horas; verifique
content_publishing_limit. - Tokens de longa duração têm cerca de 60 dias de validade. Construa a renovação antes do lançamento.
- A revisão de aplicativo é obrigatória e sua duração não é publicada na documentação.
Se você está rascunhando legendas enquanto constrói, o contador de caracteres do Instagram gratuito mostra onde o texto é truncado.
Fazendo isso uma vez, em vez de uma vez por plataforma
A alternativa a escrever isso plataforma por plataforma é uma única API que já guarda os tokens, os containers, as consultas e as tentativas de repetição. A BulkPublish publica em 15 plataformas através de uma única API REST e SDK, então uma publicação no Instagram e uma no LinkedIn são a mesma chamada com um ID de canal diferente. A renovação de token, o limite de janela móvel e a verificação de status assíncrona são tratados do nosso lado, e uma publicação que falha em uma plataforma é reportada como partial, em vez de um falso sucesso. A referência está em /pt-br/developers/ e a página de integração REST está em /pt-br/integrations/rest-api/.