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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| file_name | string | Sim | O nome do arquivo (até 255 caracteres). |
| size | integer | Sim | O tamanho exato do arquivo em bytes, de 1 até 1073741824 (1 GB). |
| upload.part_size | integer | Não | Na resposta: os bytes de cada parte. A última leva o resto. |
| upload.parts | integer | Não | Na resposta: quantas partes o arquivo tem, numeradas a partir de 1. |
| upload.expires_at | string | Não | Na resposta: até quando o upload pode ser concluído. Depois disso as partes são descartadas. |
| received_parts | array | Não | No GET /media/uploads/{uuid}: as partes já recebidas, para retomar um envio interrompido. |
| url | string | Não | Quando status é ready: a URL pública para usar em media.url do POST /posts. |
| expires_at | string | Não | Quando 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
