Ads
Enviar imagem e vídeo para o Meta Ads, o Google Ads e o TikTok Ads pela API
Uma chamada entrega uma imagem ou um vídeo, por URL, à conta de anúncios do cliente e devolve o que os anúncios usam para referenciar o arquivo: o hash da imagem ou o id do vídeo. Você envia uma vez e reaproveita em quantos anúncios quiser, sem implementar a API da Meta. No Google Ads, a rota é POST /ads/google_adwords/media e a resposta traz o asset_id. No TikTok Ads, a rota é POST /ads/tiktok_ads/media e a resposta traz o image_id da imagem ou o id do vídeo.
A chamada
POST /api/ads/facebook_ads/media?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"type": "video",
"url": "https://midias.reportei.com/connect-media/media/<file>.mp4",
"name": "Spring launch"
}O que dá para fazer
- Enviar uma imagem JPEG ou PNG por URL com POST /ads/facebook_ads/media e type: image, e receber o hash.
- Enviar um vídeo por URL com type: video e receber o id.
- Usar a URL devolvida por POST /media, que sobe o arquivo e devolve o endereço público.
- Acompanhar o processamento do vídeo com GET /ads/facebook_ads/videos/{id}, que traz status e thumbnail_url.
- Reutilizar o mesmo hash ou id em vários anúncios, como a versão de feed e a de stories do mesmo criativo.
- No Google Ads, enviar uma imagem com POST /ads/google_adwords/media e receber o asset_id, já pronto.
- No Google Ads, importar um vídeo do YouTube pelo link, pronto na hora, ou enviar um arquivo de vídeo, que sobe para o YouTube como não listado.
- No Google Ads, listar as imagens e os vídeos do YouTube que já estão na conta com GET /ads/google_adwords/library, com o asset_id, para não enviar de novo.
- No TikTok Ads, enviar o vídeo e a capa com POST /ads/tiktok_ads/media, acompanhar o vídeo com GET /ads/tiktok_ads/videos/{id} e listar o que a conta já tem com GET /ads/tiktok_ads/library.
Regras e limites
- O Idempotency-Key é obrigatório e vai sempre no header. Gere uma vez e reenvie a mesma chave nas tentativas. Repetir o mesmo pedido devolve 200 com Idempotent-Replay: true.
- A imagem fica pronta na hora. O vídeo começa em processing e só deve ir num anúncio quando o status for ready.
- O status do vídeo pode ser processing, ready ou failed. thumbnail_url é um quadro escolhido pela rede, usado como miniatura do anúncio.
- GET /ads/facebook_ads/videos/{id} só responde por vídeos que esta conta recebeu por POST /ads/facebook_ads/media. Qualquer outro id dá 404.
- O Connect não guarda o arquivo: guarde o hash ou o id do seu lado. Se um anúncio usar um vídeo ainda processando, a resposta é 409 ads_video_not_ready, e repetir com a mesma chave retoma.
- No Google Ads, um vídeo enviado por arquivo começa em processing, e GET /ads/google_adwords/videos/{id} diz quando fica ready e devolve o asset_id. O envio ao YouTube precisa terminar em 60 segundos: para um vídeo grande, publique no YouTube e mande o link.
- No TikTok Ads, a TikTok baixa o arquivo da URL. A imagem volta ready com o image_id; o vídeo começa em processing, e a TikTok costuma levar de 30 segundos a 5 minutos para deixá-lo ready.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | image ou video. |
| url | string | Sim | Endereço https público do arquivo, por exemplo a URL devolvida por POST /media. Imagem: JPEG ou PNG. |
| name | string | Não | Nome na biblioteca da conta. Sem ele, vale o nome do arquivo na URL. |
| Idempotency-Key | string | Sim | Header obrigatório, até 255 caracteres. Gere uma vez e reenvie a mesma em cada nova tentativa. |
| hash | string | Não | Na resposta, só para imagem: o que o anúncio usa para referenciá-la. Só no Meta Ads. |
| id | string | Não | Na resposta, só para vídeo: o id que o anúncio usa. Também é o {id} de GET /ads/facebook_ads/videos/{id}. |
| status | string | Não | Na resposta: ready ou processing. No GET do vídeo, também failed. |
| asset_id | string | Não | Na resposta, no Google Ads: o que o anúncio usa em google_adwords.images, logo_asset_ids e video_asset_ids. |
| video_id | string | Não | Na resposta, no Google Ads, para vídeo: o id do vídeo no YouTube. |
| image_id | Não | Na resposta, no TikTok Ads, para imagem: o que o anúncio usa em tiktok_ads.cover_image_id. |
Para quem
Biblioteca de criativos do cliente
Um SaaS de anúncios sobe os criativos do cliente uma vez e guarda o hash e o id para montar anúncios sem reenviar o arquivo.
Anúncio com versões de feed e stories
Uma agência envia dois arquivos, um por posição, e referencia cada um no mesmo anúncio.
Agente de IA que gera vídeos
Um agente gera um vídeo, envia por URL, espera o status ready e só então cria o anúncio.
Funciona com
Meta Ads
Google Ads
TikTok Ads
Perguntas frequentes
Preciso esperar o vídeo processar antes de criar o anúncio?
Sim. O vídeo começa em processing. Consulte GET /ads/facebook_ads/videos/{id} e use o id no anúncio quando o status for ready. Se usar antes, a resposta é 409 ads_video_not_ready e você repete com a mesma Idempotency-Key.
Funciona com o Google Ads e o TikTok Ads?
Sim. Use POST /ads/google_adwords/media: a resposta traz o asset_id, que o anúncio do Google usa. Um link do YouTube é importado e já volta ready; outro vídeo sobe para o YouTube, não listado, e fica pronto quando GET /ads/google_adwords/videos/{id} disser ready. No TikTok Ads, use POST /ads/tiktok_ads/media: a capa volta com o image_id e o vídeo com o id, que o anúncio usa quando GET /ads/tiktok_ads/videos/{id} disser ready.
O Connect guarda a imagem ou o vídeo?
Não. Ele entrega o arquivo à conta de anúncios e devolve o hash ou o id. Guarde esse valor do seu lado para reaproveitar nos anúncios.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
