Posts

Enviar vídeos grandes para usar em posts pela API

Os posts recebem a mídia por URL. Se você não tem onde hospedar o arquivo, envie ao Connect e receba uma URL em um domínio que as redes aceitam. Até 8 MB vai em uma única requisição; acima disso, o vídeo sobe em partes, até 1 GB, e você usa a URL no media.url do POST /posts.

A chamada

POST /api/media/uploads
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "file_name": "reels-summer.mp4",
  "size": 52428800
}

O que dá para fazer

  • Enviar um arquivo de até 8 MB em uma requisição só, com POST /media.
  • Abrir um upload em partes com POST /media/uploads para arquivos de até 1 GB.
  • Enviar as partes com PUT /media/uploads/{uuid}/parts/{part}, em paralelo depois da parte 1.
  • Retomar um envio interrompido: GET /media/uploads/{uuid} diz quais partes já chegaram.
  • Concluir com POST /media/uploads/{uuid}/complete e receber a URL pronta para usar em um post.

Regras e limites

  • POST /media aceita até 8 MB. Acima disso responde 413 media_too_large_for_single_upload e o envio vai em partes.
  • Na parte 1 o Connect lê o tipo do arquivo. A parte 1 vai primeiro; as outras podem ir em qualquer ordem e ao mesmo tempo. Reenviar uma parte substitui a anterior.
  • Cada parte exige Content-Length igual ao tamanho exato (upload.part_size, ou o resto na última). Sem ele, a resposta é 411.
  • Aceita JPEG, PNG, WebP e GIF (imagem de até 30 MB), MP4 e MOV (até 1 GB). O tipo vem do conteúdo, não do nome, e o arquivo inteiro é conferido ao concluir (422 media_content_invalid se não for válido).
  • A URL vale até expires_at, 30 dias depois de a mídia ficar ready, e então o arquivo é apagado. Quem tiver o link lê o arquivo, então só repasse a quem vai publicar.
  • POST /media e POST /media/uploads exigem o header Idempotency-Key. Até 20 uploads abertos por cliente.

Campos principais

CampoTipoObrigatórioDescrição
file_namestringSimO nome do arquivo (até 255 caracteres).
sizeintegerSimO tamanho exato do arquivo em bytes, de 1 até 1073741824 (1 GB).
upload.part_sizeintegerNãoNa resposta: os bytes de cada parte. A última leva o resto.
upload.partsintegerNãoNa resposta: quantas partes o arquivo tem, numeradas a partir de 1.
upload.expires_atstringNãoNa resposta: até quando o upload pode ser concluído. Depois disso as partes são descartadas.
received_partsarrayNãoNo GET /media/uploads/{uuid}: as partes já recebidas, para retomar um envio interrompido.
urlstringNãoQuando status é ready: a URL pública para usar em media.url do POST /posts.
expires_atstringNãoQuando a URL deixa de valer e o arquivo é apagado: 30 dias depois de a mídia ficar ready.

Para quem

  • Editor de vídeo em SaaS

    O usuário exporta um Reels de 200 MB; o produto sobe em partes e publica em Instagram e Facebook usando a URL devolvida.

  • Agência com vídeos pesados

    O painel envia os vídeos da campanha uma vez e reaproveita a mesma URL em posts de várias redes.

  • Agente de IA de vídeo

    O agente gera um vídeo, envia ao Connect em partes e passa a URL para o POST /posts sem hospedar nada.

Funciona com

  • Instagram Business
  • Facebook
  • YouTube
  • LinkedIn
  • Threads
  • Pinterest

Perguntas frequentes

Qual o tamanho máximo?

Até 8 MB em uma única requisição (POST /media) e até 1 GB em partes (POST /media/uploads). Imagens têm limite de 30 MB.

Quanto tempo a URL fica no ar?

30 dias a partir de a mídia ficar ready. Depois o arquivo é apagado, então use a URL em um post nesse prazo.

O que acontece se o envio cair no meio?

Consulte GET /media/uploads/{uuid}: received_parts lista as partes recebidas. Envie só as que faltam e conclua. O envio fica aberto até upload.expires_at.

Relacionadas

Ver tudo que dá para fazer em Posts

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.