Mídia

Cada item de mediaItems em um post aponta para uma imagem de duas formas: uma URL pública, que a Postmatic baixa e guarda, ou um mediaId de uma imagem enviada antes por upload. Nos dois casos a imagem passa pela mesma validação e é convertida para JPEG.

Por URL

{ "mediaItems": [{ "type": "image", "url": "https://cdn.exemplo.com/foto.jpg" }] }

• Só https. O host precisa resolver para um endereço público: URLs internas, localhost e IPs privados são recusados.
• Até 5 redirecionamentos, todos também https.
• Tempo limite de 30 segundos para o download.
• O download acontece na criação do post, antes da resposta. A URL não precisa continuar acessível depois.

Falha no download responde 400 MEDIA_FETCH_FAILED ou 400 MEDIA_UNREACHABLE; imagem fora dos limites responde 400 MEDIA_INVALID.

Por upload

Envie a imagem primeiro e use o id retornado nos posts. Útil quando as imagens não têm URL pública ou quando você quer validar antes de agendar.

curl -X POST https://api.uat.postmatic.dev/v1/media \
  -H "x-access-key: pm_live_…" \
  -F "file=@foto.jpg"

{
  "success": true,
  "media": { "id": "med_…", "url": "https://…/media/…jpg", "width": 1080, "height": 1350, "bytes": 412873, "mime": "image/jpeg" }
}

{ "mediaItems": [{ "type": "image", "mediaId": "med_…" }] }

• multipart/form-data, um arquivo por requisição, no campo file.
• Limite de 60 uploads por minuto por chave.
• A mesma imagem enviada duas vezes devolve o mesmo id (deduplicação por conteúdo).
• Um mediaId só vale no projeto que o criou; em outro projeto a criação do post responde 400 VALIDATION_ERROR.

Vídeo

Um vídeo publica como Reel. Há dois caminhos, e a diferença entre eles é de onde o arquivo vem na hora de publicar.

Por URL. A Postmatic lê alguns trechos do arquivo para validar e passa a mesma URL ao Instagram, que busca o vídeo. Nenhum byte é copiado. Em troca, a URL precisa continuar acessível até a publicação, o que importa para um post agendado com semanas de antecedência.

Por upload. O arquivo vai direto do seu servidor para o nosso armazenamento, sem passar pela API, e a publicação não depende mais de nada seu. É o caminho recomendado para agendamentos e para arquivos grandes.

{ "mediaItems": [{ "type": "video", "url": "https://cdn.exemplo.com/reel.mp4" }] }

Upload de vídeo em três passos

curl -X POST https://api.uat.postmatic.dev/v1/media/upload-url \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{ "filename": "reel.mp4", "mimeType": "video/mp4", "bytes": 41234567 }'

{
  "success": true,
  "upload": {
    "mediaId": "med_…",
    "path": "proj_…/med_….mp4",
    "uploadUrl": "https://…/storage/v1/object/upload/sign/…",
    "token": "…",
    "expiresIn": 7200
  }
}

curl -X PUT "$UPLOAD_URL" \
  -H "content-type: video/mp4" \
  --data-binary @reel.mp4

curl -X POST https://api.uat.postmatic.dev/v1/media/confirm \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{ "mediaId": "med_…" }'

A confirmação valida o arquivo e devolve o registro de mídia. Use o mediaId no post:

{ "mediaItems": [{ "type": "video", "mediaId": "med_…" }] }

A URL assinada vale 2 horas. Um arquivo que não passa na validação é removido do armazenamento e não vira registro.

Limites do vídeo

Vídeo sem faixa de áudio é aceito.

O índice precisa vir na frente

O Instagram exige que o índice do MP4 (a caixa moov) esteja no início do arquivo, antes dos dados de imagem. É o mesmo requisito de qualquer vídeo que começa a tocar antes de terminar de baixar, e a maioria dos editores chama a opção de faststart. Um arquivo com o índice no fim é recusado com reason: moov.

Para corrigir um arquivo existente, reescreva o contêiner sem recodificar:

ffmpeg -i entrada.mp4 -c copy -movflags +faststart saida.mp4

Limites

Quando a imagem é recusada, details.reason diz o motivo:

Carrossel exige todos os itens na mesma proporção (tolerância de 1 %): o Instagram recortaria todos para a proporção do primeiro, e preferimos recusar a surpreender.

Retenção

As imagens ficam guardadas para o post poder ser publicado e reexibido no painel. Ainda não há expiração automática nem rota para apagar mídia; veja o Roadmap.