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

CampoTipoObrigatórioDescrição
typestringSimimage ou video.
urlstringSimEndereço https público do arquivo, por exemplo a URL devolvida por POST /media. Imagem: JPEG ou PNG.
namestringNãoNome na biblioteca da conta. Sem ele, vale o nome do arquivo na URL.
Idempotency-KeystringSimHeader obrigatório, até 255 caracteres. Gere uma vez e reenvie a mesma em cada nova tentativa.
hashstringNãoNa resposta, só para imagem: o que o anúncio usa para referenciá-la. Só no Meta Ads.
idstringNãoNa resposta, só para vídeo: o id que o anúncio usa. Também é o {id} de GET /ads/facebook_ads/videos/{id}.
statusstringNãoNa resposta: ready ou processing. No GET do vídeo, também failed.
asset_idstringNãoNa resposta, no Google Ads: o que o anúncio usa em google_adwords.images, logo_asset_ids e video_asset_ids.
video_idstringNãoNa resposta, no Google Ads, para vídeo: o id do vídeo no YouTube.
image_idNãoNa 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.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

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