API do Instagram: como publicar com código em 2026

Publicar um post no Instagram a partir do seu aplicativo, script ou agente de IA parece que deveria ser uma única requisição HTTP: enviar uma legenda, anexar uma imagem e receber a URL do post publicado.

Na Graph API oficial da Meta, a publicação programática funciona de forma diferente. Publicar no Instagram é um ciclo de vida de containers assíncrono. Você cria um container de mídia, consulta o status até que a Meta termine de baixar e codificar o arquivo, e só então dispara uma requisição de publicação separada. Além disso, seu código precisa cumprir pré-requisitos rígidos de conta, hospedar mídias em servidores HTTPS públicos e lidar com fluxos específicos para imagens, Reels e carrosséis.

Este tutorial explica todo o processo. Analisamos como funcionam os endpoints nativos de containers da Meta e como publicar de forma programática usando cURL, TypeScript ou uma API de publicação unificada.

O que é a API do Instagram

A API do Instagram é a interface oficial da Meta para software que trabalha com contas profissionais do Instagram. Ela faz parte da Graph API da Meta, e é por isso que os desenvolvedores também a chamam de Instagram Graph API. Veja o que ela abrange em 2026:

O resto deste guia aborda a parte da publicação: a configuração, o fluxo de containers, as regras de mídia e código funcional.

A Meta altera a plataforma com frequência. Nossa página mensal de novidades do Instagram acompanha cada mudança e indica se ela chega à API.

Pré-requisitos: Configuração de conta e requisitos de tokens

Antes de escrever qualquer linha de código de publicação, a Meta exige três etapas de configuração administrativa. Deixar de realizar qualquer uma delas resultará em erros de permissão ((#100) Invalid parameter ou (#200) Permission denied) durante as chamadas da API.

1. O requisito de conta profissional

Perfis pessoais do Instagram não podem publicar conteúdo via API. A conta deve ser convertida para uma conta profissional do Instagram (Business ou Creator). Você pode fazer essa alteração dentro do aplicativo do Instagram em Configurações > Tipo de conta e ferramentas, ou pelo Meta Business Suite.

2. Escolher um caminho de login (e quando você precisa de uma Página do Facebook)

A Meta oferece duas formas de chegar aos mesmos endpoints de publicação:

• API do Instagram com Instagram Login: o titular da conta faz login diretamente com o Instagram. Não é necessária nenhuma Página do Facebook. A publicação usa as permissões instagram_business_basic e instagram_business_content_publish.
• API do Instagram com Facebook Login: o titular da conta faz login com o Facebook, e a conta profissional do Instagram precisa estar conectada a uma Página do Facebook que seu aplicativo consiga acessar.

No caminho do Facebook Login, conecte as contas nas configurações da sua Página do Facebook, em Contas Vinculadas e depois Instagram. Se essa conexão estiver ausente ou incompleta, a Graph API não retornará um ID de usuário do Instagram (ig-user-id) para o seu token. As permissões da etapa seguinte são as que o caminho do Facebook Login usa.

3. Permissões de aplicativo e tokens de acesso necessários

Seu aplicativo de desenvolvedor da Meta precisa das seguintes permissões para publicar conteúdo:

• instagram_basic: Para ler o ID da conta do Instagram conectada e metadados básicos de perfil.
• instagram_content_publish: Para criar containers e publicar posts.
• pages_show_list e pages_read_engagement: Para localizar a Página do Facebook associada à conta do Instagram.

Para desenvolvimento, você pode gerar um token de curta duração pelo Graph API Explorer. Para sistemas em produção, troque esse token por um token de usuário de longa duração de 60 dias, ou implemente o Facebook Login com OAuth 2.0 para solicitar permissões dinamicamente.

Como funciona a publicação nativa na Meta: O fluxo de containers em 3 etapas

A Meta separa a publicação de conteúdo em três etapas distintas porque o processamento de mídia consome tempo. Em vez de manter uma conexão HTTP aberta enquanto o Instagram baixa, valida e transcodifica um vídeo ou imagem de alta resolução, a API utiliza um ciclo de vida de containers.

Etapa 1: Criar o container de mídia

Você começa enviando uma requisição POST para o endpoint /media da conta. Você informa a URL da imagem, a legenda e o seu token de acesso.

curl -X POST "https://graph.facebook.com/v21.0/$IG_USER_ID/media" \
  -F "image_url=https://cdn.example.com/images/spring-launch.jpg" \
  -F "caption=Spring collection is live. Shop the link in bio." \
  -F "access_token=$META_ACCESS_TOKEN"

Se os parâmetros estiverem válidos, a Meta retorna um ID de container:

{
  "id": "17895695634123456"
}

Esse container ainda não é visível no Instagram. Ele é um objeto temporário nos servidores da Meta.

Etapa 2: Consultar o status do container

Antes de publicar, é necessário verificar se a Meta concluiu o processamento do arquivo. Consulte o campo status_code do container:

curl -X GET "https://graph.facebook.com/v21.0/$CONTAINER_ID?fields=status_code&access_token=$META_ACCESS_TOKEN"

A Meta retorna um dos quatro status:

• IN_PROGRESS: O arquivo de mídia ainda está sendo baixado ou processado. Aguarde alguns segundos e consulte novamente.
• FINISHED: O container está pronto para publicação.
• ERROR: O processamento falhou (por exemplo, o arquivo estava inacessível ou corrompido).
• EXPIRED: O container não foi publicado em até 24 horas após sua criação.

Para imagens, o status geralmente muda para FINISHED em menos de dois segundos. Para vídeos, o processamento pode levar de 15 a 45 segundos, dependendo do tamanho do arquivo e da carga do servidor.

Etapa 3: Publicar o container

Quando o status alcançar FINISHED, dispare a chamada final de publicação passando o ID do container como creation_id no endpoint /media_publish:

curl -X POST "https://graph.facebook.com/v21.0/$IG_USER_ID/media_publish" \
  -F "creation_id=$CONTAINER_ID" \
  -F "access_token=$META_ACCESS_TOKEN"

A Meta retorna o ID do objeto de mídia publicado no Instagram:

{
  "id": "17923485729987654"
}

O post agora está publicado no perfil do Instagram da conta.

Restrições de mídia: URLs públicas, formatos e Reels

A Content Publishing API da Meta impõe restrições técnicas específicas aos arquivos de mídia enviados.

Apenas URLs HTTPS públicas

A Meta não aceita uploads diretos de arquivos binários na criação de containers de mídia. Seu aplicativo precisa enviar a imagem ou vídeo para um armazenamento em nuvem (como Amazon S3, Cloudflare R2 ou uma CDN pública) e informar essa URL para a Meta.

A URL precisa atender a três critérios:

1. Precisa ser acessível via HTTPS.
2. Não pode exigir cabeçalhos de autenticação nem cookies privados.
3. O servidor precisa retornar cabeçalhos Content-Type corretos (image/jpeg ou video/mp4).

Especificações de imagem e proporções de tela

• Formato: O formato JPEG é obrigatório para publicações no feed. Embora PNG funcione para stories em certos contextos, o feed exige JPEG.
• Tamanho máximo de arquivo: 8 MB.
• Proporção de tela (Aspect Ratio): Deve estar entre 4:5 (vertical, proporção 0.8) e 1.91:1 (horizontal). Se a imagem estiver fora dessa faixa, a criação do container retornará um erro de proporção.

Vídeos são publicados como Reels

Todo upload individual de vídeo enviado pela Content Publishing API é publicado como um Instagram Reel. O formato clássico de vídeo no feed foi unificado com o Reels em toda a plataforma.

• Formato: Container MP4 ou MOV com codec de vídeo H.264 e áudio AAC.
• Duração: Entre 3 segundos e 15 minutos.
• Tamanho máximo de arquivo: 1 GB.
• Proporção de tela: Recomendado 9:16 (1080x1920 pixels), com taxa de quadros máxima de 60 fps.

Carrosséis exigem containers secundários

Publicar um carrossel com múltiplas imagens ou vídeos adiciona uma camada extra de containers aninhados:

1. Crie um container secundário para cada imagem ou vídeo definindo is_carousel_item=true.
2. Consulte o status de cada container secundário até que todos retornem FINISHED.
3. Crie um container principal com media_type=CAROUSEL e passe a lista de IDs dos containers secundários no parâmetro children.
4. Publique o container principal em /media_publish.

Os carrosséis aceitam de 2 a 10 itens e permitem misturar imagens e vídeos na mesma publicação.

A rota de trabalho único: Publicando com a InvisibleAPI

Construir e manter esse fluxo nativo de containers em múltiplas contas gera um custo operacional alto: armazenamento de credenciais, rotinas de renovação de tokens, mapeamento de Páginas do Facebook, orquestração de containers secundários e rotinas de polling.

A InvisibleAPI oferece um motor unificado de publicação social. Em vez de coordenar fluxos complexos de containers por plataforma, você envia um único trabalho de publicação assíncrono.

POST /api/v1/organizations/{organization}/publishing/jobs -> 202 Accepted

A plataforma valida o payload antes do envio, cria os containers necessários, monitora o progresso de codificação e gerencia erros transitórios automaticamente.

O ciclo de vida do trabalho

Ao enviar uma requisição de publicação, a InvisibleAPI retorna um objeto de trabalho assíncrono imediatamente:

{
  "id": "job_01JH8M5V9W2Q4K7X1P0R",
  "status": "processing",
  "clientRequestId": "blog-announcement-2026-09-21",
  "targets": ["acct_ig_8f29c41a"]
}

O trabalho avança por estados documentados: pending, processing, submitted e polling, até chegar a um status final:

• published: Publicado com sucesso no Instagram.
• failed: Falha permanente (por exemplo, dimensões de imagem inválidas).
• action_required: Credenciais da conta expiradas ou desconectadas.
• partial_failure: O trabalho tinha várias contas como destino e algumas falharam.
• canceled: O trabalho foi cancelado antes de ser publicado.

Exemplos de código: Imagens, Reels e Carrosséis

Abaixo você confere como publicar diferentes formatos de mídia utilizando TypeScript limpo e sem dependências externas.

Exemplo 1: Publicando uma única imagem (cURL e TypeScript)

Primeiro, a requisição cURL direta para disparar uma publicação com imagem única:

curl -X POST "https://api.invisibleapi.ai/api/v1/organizations/$ORG_ID/publishing/jobs" \
  -H "Authorization: Bearer $INVISIBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["acct_ig_8f29c41a"],
    "caption": "Exploring the coast. Photo taken at sunset.",
    "mediaItems": [
      {
        "mediaType": "image",
        "sourceUrl": "https://cdn.example.com/photos/coast-sunset.jpg"
      }
    ],
    "clientRequestId": "sunset-post-001"
  }'

Em TypeScript, você pode estruturar o envio do trabalho e a verificação de status em uma função direta:

interface PublishResult {
  jobId: string;
  status: string;
}

export async function publishInstagramImage(
  orgId: string,
  targetAccountId: string,
  imageUrl: string,
  caption: string,
  clientRequestId: string
): Promise<PublishResult> {
  const apiKey = process.env.INVISIBLE_API_KEY;

  // 1. Submit the asynchronous publishing job
  const response = await fetch(
    `https://api.invisibleapi.ai/api/v1/organizations/${orgId}/publishing/jobs`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        targets: [targetAccountId],
        caption,
        mediaItems: [{ mediaType: "image", sourceUrl: imageUrl }],
        clientRequestId,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Job creation failed: ${response.statusText}`);
  }

  const job = await response.json();
  return { jobId: job.id, status: job.status };
}

Exemplo 2: Publicando um Reel em vídeo

Para publicar um Reel, basta alterar o mediaType para video e fornecer uma URL de arquivo MP4. Como a codificação de vídeo leva mais tempo, a rotina de polling consulta o status do trabalho até que ele mude para published:

export async function publishInstagramReel(
  orgId: string,
  targetAccountId: string,
  videoUrl: string,
  caption: string,
  clientRequestId: string
) {
  const apiKey = process.env.INVISIBLE_API_KEY;

  const res = await fetch(
    `https://api.invisibleapi.ai/api/v1/organizations/${orgId}/publishing/jobs`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        targets: [targetAccountId],
        caption,
        mediaItems: [{ mediaType: "video", sourceUrl: videoUrl }],
        clientRequestId,
      }),
    }
  );

  if (!res.ok) {
    throw new Error(`Job creation failed: ${res.status} ${await res.text()}`);
  }

  const job = await res.json();
  return pollUntilComplete(orgId, job.id);
}

const TERMINAL_STATUSES = new Set([
  "published",
  "partial_failure",
  "failed",
  "action_required",
  "canceled",
]);

async function pollUntilComplete(orgId: string, jobId: string, maxAttempts = 20) {
  const apiKey = process.env.INVISIBLE_API_KEY;

  for (let i = 0; i < maxAttempts; i++) {
    await new Promise((resolve) => setTimeout(resolve, 3000));

    const pollRes = await fetch(
      `https://api.invisibleapi.ai/api/v1/organizations/${orgId}/publishing/jobs/${jobId}`,
      { headers: { "Authorization": `Bearer ${apiKey}` } }
    );
    if (!pollRes.ok) {
      throw new Error(`Job lookup failed: ${pollRes.status}`);
    }
    const data = await pollRes.json();

    if (TERMINAL_STATUSES.has(data.status)) {
      return data;
    }
  }

  throw new Error("Job polling timed out before reaching a terminal state.");
}

Exemplo 3: Publicando um carrossel

Para publicar um carrossel, informe múltiplos objetos em mediaItems. É possível combinar imagens e vídeos na mesma requisição:

export async function publishInstagramCarousel(
  orgId: string,
  targetAccountId: string,
  items: Array<{ type: "image" | "video"; url: string }>,
  caption: string,
  clientRequestId: string
) {
  const apiKey = process.env.INVISIBLE_API_KEY;

  const response = await fetch(
    `https://api.invisibleapi.ai/api/v1/organizations/${orgId}/publishing/jobs`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        targets: [targetAccountId],
        caption,
        mediaItems: items.map((item) => ({
          mediaType: item.type,
          sourceUrl: item.url,
        })),
        clientRequestId,
      }),
    }
  );

  return response.json();
}

Nos bastidores, a API gera automaticamente os containers secundários para cada item, aguarda a conclusão da codificação de todos eles, monta o container principal do carrossel e executa a publicação final.

Confiabilidade em produção: Idempotência, limites e tratamento de falhas

Colocar a publicação social em produção exige proteção contra instabilidades de rede e esgotamento de cotas.

Prevenindo publicações duplicadas com clientRequestId

Falhas de conexão acontecem. Se uma requisição expirar aguardando resposta do servidor, um cliente comum tentará reenviar a chamada. Sem garantia de idempotência, esse reenvio gera uma publicação duplicada no perfil do usuário.

A InvisibleAPI aceita um parâmetro opcional clientRequestId (com até 128 caracteres). Se o seu aplicativo enviar uma requisição com um clientRequestId que corresponda a um trabalho já recebido, o servidor retornará o registro do trabalho existente em vez de realizar um novo disparo:

# Safe retry with identical clientRequestId
curl -X POST "https://api.invisibleapi.ai/api/v1/organizations/$ORG_ID/publishing/jobs" \
  -H "Authorization: Bearer $INVISIBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": ["acct_ig_8f29c41a"],
    "caption": "Product launch details.",
    "mediaItems": [{"mediaType": "image", "sourceUrl": "https://cdn.example.com/p1.jpg"}],
    "clientRequestId": "product-launch-v1"
  }'

Se os dados da requisição forem diferentes para uma chave já existente, a API retornará o erro 409 publishing.idempotency_mismatch, alertando sobre a divergência no payload.

Limites de frequência e cotas da plataforma

A Meta aplica uma regra estrita de publicação: 100 publicações via API em uma janela móvel de 24 horas por conta do Instagram.

• Uma única imagem ou Reel conta como uma publicação.
• Um carrossel com 10 itens também conta como uma única publicação para essa cota.
• Vários tutoriais antigos citam um limite desatualizado de 25 posts por dia. A Meta atualizou essa cota para 100 publicações a cada 24 horas.

Se seu aplicativo ultrapassar esse limite, a Meta retornará o código 9 com o subcódigo 2207042, e a orientação dela é tentar novamente no dia seguinte. Monitore o volume de disparos localmente para distribuir os envios ao longo dos dias caso opere fluxos intensos de publicação.

Classificação de falhas: Erros do remetente versus instabilidade da plataforma

Quando uma publicação falha, identificar a causa raiz orienta a resposta adequada do seu sistema:

• Erros do remetente (invalid_publish_data): Causados por proporções de tela inválidas, legendas com mais de 2.200 caracteres ou URLs de arquivos inacessíveis. Reenviar sem alterar os dados falhará continuamente.
• Erros transitórios da plataforma (retryable_provider_failure): A infraestrutura de processamento da Meta teve uma instabilidade momentânea. O trabalho de publicação tenta novamente de forma automática.
• Problemas de credenciais (provider_action_required): O usuário alterou a senha do Instagram, revogou acessos do aplicativo ou o token de 60 dias expirou. Isso exige reautenticar a conta.

Se você implementar as novas tentativas por conta própria, nosso guia de códigos de erro da API do Instagram classifica cada código documentado em repetir, corrigir, escalar ou parar. Para executar a publicação de forma agendada a partir do seu próprio código, veja como automatizar publicações no Instagram com uma fila e uma política de falhas.

Para mais detalhes sobre as restrições da plataforma, consulte como funcionam as restrições e limites de contas no Instagram ou veja como um modelo de limites de publicação em redes sociais gerencia esperas.

Próximos passos para a sua implementação

Publicar no Instagram programaticamente se resume a gerenciar o ciclo de vida dos containers. Se você está criando uma integração pontual para uma única conta, os endpoints da Graph API da Meta oferecem controle direto sobre as três fases de containers.

Se você está desenvolvendo uma plataforma, ferramenta interna ou agente de IA que publica em várias contas, gerenciar tokens, containers secundários e tratamento de erros no próprio código consome tempo rapidamente, e é exatamente esse trabalho que a API de publicação no Instagram tira das suas mãos. A seguir, leia o nosso guia sobre como conectar uma conta do Instagram ou use o nosso modelo de calendário de publicação em redes sociais.

Fontes

• Meta for Developers: Documentação da Instagram Content Publishing API (Graph API v21.0, verificado em setembro de 2026).
• Meta for Developers: Referência de containers de mídia e status do Instagram.
• Termos da Plataforma Meta: Políticas de publicação automatizada e padrões de segurança de tokens.
• Referência da InvisibleAPI: Documentação da API de trabalhos de publicação.