Como publicar carrossel no Instagram via API
Como montar e publicar um carrossel de até 10 itens no Instagram usando a API.
Por André LugUm carrossel no Instagram, na hora de chamar a API, é só um post normal com um array de mídia mais longo — em vez de uma única foto ou vídeo, você passa até 10 itens, e o Instagram monta a experiência de deslizar entre eles automaticamente. Não existe um endpoint separado para carrossel: é o mesmo POST /api/posts de qualquer outro post.
Se você ainda não publicou nada pela API, veja primeiro o passo a passo geral de como postar no Instagram via API.
Um carrossel é um array, não um recurso separado
A diferença inteira entre um post de foto único e um carrossel está no campo media: com um item, é um post normal; com mais de um, até o limite de 10 itens, o Instagram trata como carrossel. A ordem dos itens no array é a ordem em que eles aparecem para quem desliza o post.
Montar a chamada com múltiplos itens
Cada item pode ser uma URL pública de imagem ou vídeo, ou um ID de mídia pré-enviado. O restante do envelope — corpo do post, perfis de destino, chave de idempotência — não muda em relação a um post de item único.
curl -X POST https://postgate.studio/api/posts \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: carrossel-lancamento-01" \
-d '{
"post": { "body": "Antes e depois — deslize para ver tudo." },
"profiles": ["pro_instagram123"],
"media": [
"https://cdn.example.com/slide-1.jpg",
"https://cdn.example.com/slide-2.jpg",
"https://cdn.example.com/slide-3.mp4"
]
}'Misturar foto e vídeo no mesmo carrossel
O Instagram permite combinar imagens e vídeos dentro do mesmo carrossel, como no exemplo acima. Cada item ainda precisa passar individualmente pela validação de formato da plataforma — um vídeo com proporção ou codec fora do aceito derruba aquele item específico, mesmo que os outros estejam corretos.
Pré-validar cada item antes de publicar
Para carrosséis com itens grandes, reutilizados, ou que vêm de um pipeline de geração de conteúdo, vale enviar cada mídia antecipadamente pelo endpoint dedicado e aguardar o estado ready antes de montar o post — assim, um item com problema é identificado antes da tentativa de publicação, item por item, em vez de derrubar o carrossel inteiro na hora de publicar.
Ler o resultado do carrossel
Um carrossel publicado é um post só, com um único target por destino — o link permanente e o ID retornado pela Meta se referem ao carrossel completo, não a cada item individualmente. Se algum item específico falhar na validação antes da publicação, o erro aparece no target daquele destino, identificando qual parte do envelope causou o problema.
