Referência completa da CLI

Esta é a referência completa da CLI do Ads Uploader. Para uma introdução e um guia de configuração, veja Configuração da CLI.

Comandos

Autenticação

Um token de login dura 30 dias. Depois disso, rode ads login de novo.

Chaves de API para seus próprios agentes e scripts

Veja Chaves de API para a configuração completa e as regras de uso por uma só pessoa. Para seus próprios agentes e scripts, abra Account > MCP, CLI & API, escolha Create API Key e dê um nome à chave. Copie o segredo adk_ quando ele aparecer; ele é exibido apenas uma vez. Você pode ter uma chave ativa por padrão. Adicione uma vaga na equipe para outra pessoa ou entre em contato com o suporte se precisar de mais chaves. As chaves funcionam em redes diferentes e exigem acesso à CLI na sua conta. Elas não expiram. Chaves sem uso por 90 dias são revogadas, e enviamos um email quando isso acontece. O tempo em que seu plano está pausado não conta.

Defina ADS_API_KEY nas configurações de segredos do servidor ou do sistema de CI. Ela tem prioridade sobre o token salvo em ~/.config/adsuploader/credentials.json. Para salvar uma chave localmente, rode:

ads login --api-key

Cole a chave no prompt de entrada oculta ou passe pelo stdin. A CLI verifica a chave antes de salvar. Evite colocar o segredo no comando, onde ele pode aparecer no histórico do shell. ads whoami e ads config mostram o método de autenticação; só o prefixo da chave é exibido.

Escolha Revoke em API Keys, dentro de Account > MCP, CLI & API, quando não precisar mais de uma chave. ads logout remove a chave salva daquela máquina sem revogá-la. Ele não consegue remover ADS_API_KEY; remova essa variável do ambiente ou das configurações de segredos. Você pode revogar os logins pelo navegador em MCP and CLI-Connected AI Apps. Ao sair de uma sessão, a CLI também tenta revogá-la.

Navegação

Builds salvos

Os builds salvos são os mesmos que você vê na janela Saved Builds do uploader web. Veja Builds salvos para entender como funcionam.

Passe - no lugar do nome do arquivo para ler o JSON do stdin. Para lançar um build, use ads create --build <buildId> (ou create:preview).

Upload de mídia

Argumentos HTTPS, incluindo links públicos de arquivos do Google Drive, são detectados automaticamente. Você pode misturar caminhos locais e URLs: os arquivos locais sobem primeiro, e depois o servidor importa as URLs para o mesmo lote, para que o agrupamento funcione entre todas as entradas. Pastas públicas do Drive precisam estar compartilhadas como Anyone with the link (Viewer).

Os arquivos locais são preparados em paralelo, e falhas de rede passageiras são repetidas automaticamente com espera progressiva. Importações de URL e de pasta do Drive usam pipelines de arquivos em paralelo, com limite, em um job em segundo plano, enquanto a CLI mostra um contador de concluídos/total e cada arquivo ativo. Você raramente precisa mexer nestas flags, mas elas estão disponíveis:

Regras de upload:

• Cada arquivo pode ter até 4 GB.
• Imagens: .jpg, .jpeg, .png, .gif, .bmp, .webp. Vídeos: .mp4, .mov, .avi, .mkv, .webm, .m4v.
• Os links precisam usar https://. Qualquer outra coisa é tratada como caminho local.
• Uma imagem com o nome do vídeo mais _thumbnail (por exemplo promo_thumbnail.jpg para promo.mp4) é associada a esse vídeo como thumbnail personalizada, em vez de subir como mídia separada.
• Pressionar Ctrl-C durante uma importação por link ou do Drive pede ao servidor que pare a importação. Os arquivos que já terminaram continuam no lote.

Criação de anúncios

Duplicação por Post ID

Gestão de jobs

Flags de criação

Estas flags valem para ads create, ads create:preview e ads create:interactive. Você pode usá-las no lugar de um arquivo de especificação, ou junto com ele.

Flags de duplicação por Post ID

As duplicações por agentes via MCP, CLI e API pública seguem a configuração Agent Launch da conta na página Account Permissions, assim como os lançamentos. Agent Edit não se aplica a elas. Allowed (o padrão) inicia a cópia diretamente. Approval retorna pending_approval e reviewUrl; nada é duplicado até o usuário aprovar na página Agent Inbox. Compartilhe o link; não repita a solicitação nem consulte um job, pois ele só existe após a aprovação. Off recusa a solicitação com AGENT_LAUNCH_DISABLED. Cópias ACTIVE comuns podem exigir confirmação explícita com confirmSpend: true (--confirm-spend na CLI); cópias por Post ID nunca exigem. Uploads de novas mídias e o Duplicator web operado por uma pessoa continuam iguais.

Estas flags valem para ads duplicator:post-id e ads duplicator:post-id:preview. Elas podem ser usadas no lugar de um arquivo de especificação de duplicação por Post ID, ou junto com ele. Este é o modo de duplicação por Post ID; outros modos de duplicação podem ser adicionados depois.

Arquivo de especificação de duplicação por Post ID

Esta especificação v1 seleciona um anúncio de origem exato, clona um conjunto de anúncios e cria anúncios pausados:

{
  "adIds": ["120200000000000001"],
  "campaignId": "120200000000000000",
  "adSetId": "120200000000000002",
  "newAdSet": { "name": "Winners {AdName}" },
  "adNamePattern": "{AdName} - {Index}",
  "paused": true,
  "useCreativeId": false
}

Use postIds para busca ou adIds em ordem para seleção exata, nunca os dois. A prévia retorna sourceCandidates com os IDs de anúncio, campanha e conjunto de anúncios. Quando as correspondências são ambíguas, requiresSourceSelection é true e resolvedRequest é null: escolha os IDs dos anúncios e veja a prévia de novo. Com uma seleção exata, resolvedRequest contém IDs de anúncio e nenhum ID de publicação. Um campaignId existente é obrigatório; novas campanhas não são suportadas.

Escolha um modo de destino de conjunto de anúncios:

Em execuções reais com avisos de criativo, revise a prévia e passe --acknowledge-warnings (acknowledgeWarnings: true no JSON ou no MCP) para continuar. Um useCreativeId: true explícito também atende essa escolha. A prévia não exige essa confirmação.

A campanha de destino, o conjunto de anúncios selecionado e os anúncios de origem precisam pertencer à mesma conta de anúncio. Um conjunto de anúncios selecionado precisa pertencer a campaignId, inclusive quando usado como modelo para um novo conjunto. Escolha newAdSet ou newAdSetPerAd; combinar os dois é rejeitado. Uma única origem com newAdSetPerAd cria um único clone compartilhado e mantém {Index} como 1.

A prévia lê a configuração real de cada anúncio de origem e de cada modelo selecionado, sem criar objetos na Meta. Por isso, origens posteriores podem revelar dados faltando e avisos de criativo; a segmentação é validada em cada modelo usado para criar um novo conjunto de anúncios. Novos conjuntos de anúncios simulados usam as configurações de orçamento e de lance da campanha de destino, quando disponíveis. Os anúncios são ativos por padrão; paused afeta só os anúncios, e os novos conjuntos de anúncios continuam ativos.

{AdName} insere o nome do anúncio de origem. {Index} insere a ordem dele, começando em 1, nos nomes dos anúncios duplicados e nos nomes de conjunto de anúncios por anúncio. Quando um novo conjunto de anúncios contém vários anúncios de origem, {AdName} no nome desse conjunto vira Multiple Ads.

Como a busca por publicação escolhe os anúncios: uma busca por ID de publicação procura em até cerca de 2.000 anúncios recentes da conta. Ela nunca escolhe a correspondência mais recente por você. Quando vários anúncios correspondem, a CLI e o MCP param e pedem que você escolha, e também param diante de avisos que você não confirmou. Uma execução real sempre duplica IDs exatos de anúncio, então envie o resolvedRequest da prévia. Para repetir uma seleção que você já revisou, salve e reutilize o resolvedRequest (o MCP também precisa do accountId) em vez de repetir a busca só pela publicação. Os IDs dos anúncios ficam fixos, mas as configurações atuais da Meta são lidas e verificadas de novo no lançamento.

Novos conjuntos de anúncios herdam a segmentação, o orçamento, a programação e as configurações de lance do --adset ou adSetId selecionado, com a mesma limpeza e o mesmo ajuste ao orçamento do destino do Duplicator da web. Sem um modelo selecionado, um novo conjunto compartilhado usa o conjunto do primeiro anúncio de origem; o modo por anúncio usa o próprio conjunto de cada anúncio de origem.

Anúncios de origem com criativo dinâmico reutilizam o ID do criativo e não conseguem manter o engajamento sincronizado. A CLI mostra o mesmo aviso do Duplicator da web.

Execuções reais de duplicação por Post ID mostram o progresso por conjunto de anúncios e por anúncio, incluindo as mensagens de erro da Meta, e terminam com Duplicated X of Y.

Flags de navegação

Estas flags estão disponíveis em campaigns, adsets, adset e campaign:

Targeting Search

Cidade, CEP e segmentação detalhada usam identificadores da Meta, e não nomes. Pesquise pelo Ads Uploader para obter valores que podem ser colados em uma especificação:

ads targeting:search "Austin" --type city
ads targeting:search "90210" --type zip
ads targeting:search "advertising" --type detailed

Os resultados de segmentação detalhada incluem id, name, type, uma faixa de tamanho de público e o caminho da categoria. O type identifica a categoria de segmentação detalhada, como interests, behaviors, work_employers ou work_positions. Sempre pesquise esses identificadores; nunca tente adivinhá-los.

Flags de detalhe

Estas flags estão disponíveis em ad:

Flags comuns

Variáveis de ambiente e atualizações

A CLI procura uma nova versão uma vez por dia e mostra um aviso quando há uma. Atualize com npm update -g @adsuploader/cli.

Formato do arquivo de especificação

O arquivo de especificação JSON controla todos os aspectos da criação de anúncios. Informe uma fonte de modelo (adPresetId ou copyFromAd) mais um uploadId ou mediaItems capturados, com um mediaHash do Facebook para cada imagem e um mediaId para cada vídeo. Vídeos padrão, de carrossel, flexíveis e de posicionamento também precisam de thumbnailHash; vídeos Multi Media usam a URL pública da thumbnail capturada.

Para vídeos, mediaItems[].mediaId precisa ser o ID numérico do vídeo no Facebook: use o videoId da resposta do upload, não o id interno. videoId é aceito como alias, e linkedAssets[] seguem a mesma regra. IDs internos de upload só são resolvidos ao salvar quando pertencem ao usuário autenticado e à conta selecionada. Sem um ID numérico ou um vínculo de lote, um vídeo não resolvido torna o build impossível de lançar. Veja o item canônico de vídeo com posicionamento.

Especificação mínima

{
  "adPresetId": "your_preset_id",
  "uploadId": "batch_abc123"
}

Exemplo completo

{
  "adPresetId": "preset_id_here",
  "uploadId": "batch_abc123",
  "adSet": {
    "name": "My New Ad Set",
    "dailyBudget": 50
  },
  "adNamePattern": "{filename}",
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Main Headline"],
        "bodies": ["Ad copy here."],
        "descriptions": ["Short description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/landing"
      }
    }
  },
  "creativeEnhancements": "none",
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet"
  }
}

Fonte do modelo

Você precisa de um destes campos para dizer à CLI qual configuração de anúncio usar como base.

Ao usar copyFromAd, informe o lote de upload, ou lance um build salvo na web cujas imagens capturadas têm mediaHash e cujos vídeos têm mediaId. Opcionalmente, você pode definir a campanha e o conjunto de anúncios:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "campaign": { "id": "120233848666410472" },
  "adSet": { "id": "120233848666620472" }
}

Para encontrar o ID certo do anúncio, navegue pela sua conta: ads campaigns, depois ads campaign <id>, depois ads adset <id> e depois ads ad <id>.

Opções de perfil

Por padrão, os novos anúncios herdam a Página do Facebook, a conta do Instagram e o perfil do Threads do anúncio modelo ou do preset. É o mesmo controle Profile Options disponível pelo painel Defaults no app web. Substitua qualquer um deles com um bloco profile (ou com as flags --page / --instagram / --use-page-identity / --threads, que têm prioridade sobre o arquivo de especificação):

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "profile": {
    "pageId": "123456789012345",
    "instagramId": "17841400000000000",
    "threadsId": "987654321098765"
  }
}

Rode ads pages para listar os IDs de Página que você pode usar, junto com a conta do Instagram vinculada a cada Página.

Se você substituir só a Página, Ads Uploader usa automaticamente a conta do Instagram vinculada a ela. Se nenhuma conta do Instagram estiver vinculada, ele usa a Página do Facebook como identidade no Instagram. O Threads continua sendo redefinido, porque pode pertencer à Página antiga; defina-o explicitamente quando precisar.

Para escolher explicitamente a Página como identidade, use --use-page-identity ou defina "useFacebookPage": true dentro de profile. Não combine com --instagram nem com instagramId. Você também pode mudar só o perfil do Instagram ou do Threads, sem mexer na Página, definindo apenas esses campos.

Em lançamentos com várias campanhas, atribua identidades a cada uma de forma independente com profile.campaigns. Use como chave de cada substituição o id da campanha correspondente (recomendado) ou um nome de campanha sem ambiguidade:

{
  "campaign": {
    "mode": "duplicate",
    "campaigns": [
      { "id": "prospecting", "name": "Prospecting" },
      { "id": "retargeting", "name": "Retargeting" }
    ]
  },
  "profile": {
    "campaigns": {
      "prospecting": { "pageId": "page_1", "instagramId": "ig_1", "threadsId": null },
      "retargeting": { "pageId": "page_2", "useFacebookPage": true, "threadsId": "threads_2" }
    }
  }
}

profile.campaigns só funciona quando campaign.mode é "duplicate" ou "split", com pelo menos duas entradas em campaign.campaigns. Cada chave precisa corresponder a uma dessas campanhas; chaves sem correspondência ou ambíguas são rejeitadas antes do lançamento.

Estrutura da campanha

Por padrão, os anúncios vão para a campanha do anúncio modelo. Você pode criar uma nova campanha informando campaign.name.

Para os modos com várias campanhas, use campaign.mode com um array campaigns:

{
  "campaign": {
    "mode": "duplicate",
    "campaigns": [
      { "name": "Campaign A" },
      { "name": "Campaign B" }
    ]
  }
}

Modos de conjunto de anúncios

Por padrão, os anúncios vão para o conjunto de anúncios existente do anúncio modelo. Os modos a seguir dão controle sobre como os anúncios são distribuídos entre os conjuntos de anúncios.

Criar um novo conjunto de anúncios:

{ "adSet": { "name": "My Ad Set" } }

Usar um conjunto de anúncios existente pelo ID:

{ "adSet": { "id": "120233848666620472" } }

Um conjunto de anúncios por arquivo enviado:

{ "adSet": { "mode": "perUpload" } }

Agrupar automaticamente em conjuntos de anúncios de tamanho fixo:

{ "adSet": { "mode": "autoGroup", "adsPerAdSet": 5 } }

Grupos personalizados, com controle total sobre quais arquivos vão para onde:

{
  "adSet": {
    "groups": [
      { "name": "Images - April 10", "media": ["hero.jpg", "banner.jpg"] },
      { "name": "Videos - April 10", "media": ["promo.mp4"] }
    ]
  }
}

Padrão de nome de conjunto de anúncios para os modos com vários conjuntos:

{ "adSet": { "mode": "perUpload", "namePattern": "Ad Set {index:01}" } }

Agrupamento de variantes agrupa os anúncios pelo identificador de variação no mesmo conjunto de anúncios:

{ "adSet": { "mode": "autoGroup", "groupVariations": true, "variationIdentifier": "-" } }

Substituição de orçamento e de controle de lance

Substitua o orçamento diário e/ou o valor do lance nos novos conjuntos de anúncios. Os valores estão nas unidades da moeda da sua conta (por exemplo 50 para $50 ou 50 euros).

dailyBudget e bidAmount usam unidades da moeda da conta. minimumRoas é uma razão, então 1.5 significa uma meta de ROAS de 1,5x.

• Campanhas ABO (o orçamento fica no conjunto de anúncios): combine dailyBudget com bidAmount para estratégias de limite de lance ou de custo, ou com minimumRoas para LOWEST_COST_WITH_MIN_ROAS.
• Campanhas CBO (o orçamento fica na campanha): não defina dailyBudget no conjunto de anúncios. Defina campaign.dailyBudget ou campaign.lifetimeBudget (um exclui o outro) para substituir o orçamento da campanha de origem, ou omita os dois para herdá-lo. Os limites de gasto mínimo e máximo do conjunto de anúncios podem usar valores em unidades inteiras ou de 5% a 100% do orçamento da campanha, em passos de 5%; os limites em porcentagem também funcionam com uma campanha CBO existente. Defina bidAmount ou minimumRoas no conjunto de anúncios quando a estratégia de origem dele usa esse controle.

bidAmount e minimumRoas são mutuamente exclusivos porque pertencem a estratégias de lance diferentes.

{ "adSet": { "dailyBudget": 50 } }
{ "adSet": { "bidAmount": 5 } }
{ "adSet": { "minimumRoas": 1.5 } }
{ "adSet": { "dailyBudget": 50, "bidAmount": 5 } }

Para limites de gasto CBO em uma especificação, defina estes campos em adSet:

{
  "campaign": { "dailyBudget": 200 },
  "adSet": { "minSpend": 20, "maxSpendPercentage": 50 }
}

Também disponíveis como flags da CLI: --daily-budget 50, --bid-amount 5, --minimum-roas 1.5, --campaign-daily-budget 100, --campaign-lifetime-budget 1000, --adset-min-spend 20, --adset-max-spend 80, --adset-min-spend-pct 20 e --adset-max-spend-pct 80.

Ad Set Targeting

A segmentação vale para novos conjuntos de anúncios. Omita o bloco targeting de nível superior para herdar sem mudanças o público do conjunto de anúncios de origem. Qualquer modo pode usar adSet.targetingPerAdSet, com chaves como em texts.perAdset: pelo nome final do conjunto de anúncios, pelo ID do conjunto de anúncios ou por campaign::key, que evita colisões. O modo personalizado também suporta adSet.groups[].targeting. A ordem de prioridade é targetingPerAdSet, depois groups[].targeting, depois o padrão do build e depois o público de origem. A segmentação por conjunto de anúncios só existe na especificação, porque as flags da CLI não conseguem apontar para um conjunto de anúncios planejado específico.

Com várias campanhas, a cópia de um conjunto de anúncios em cada campanha é segmentada separadamente; use "Campaign name::Ad set name" como chave para uma cópia específica.

{
  "targeting": {
    "countries": ["US"],
    "cities": [
      {
        "key": "2525495",
        "name": "Austin",
        "region": "Texas",
        "countryCode": "US",
        "radius": 25,
        "distance_unit": "mile"
      }
    ],
    "zips": [
      {
        "key": "US:90210",
        "name": "90210",
        "region": "California",
        "countryCode": "US"
      }
    ],
    "selectionVersion": 4,
    "ageSelected": true,
    "ageMin": 21,
    "ageMax": 55,
    "genderSelected": true,
    "genders": "women",
    "detailedTargetingSelected": true,
    "detailedTargetingGroups": [[
      {
        "id": "112002898811624",
        "name": "Advertising agency",
        "type": "work_employers"
      }
    ]]
  }
}

{
  "targeting": { "countries": ["US"], "ageMin": 21, "ageMax": 55 },
  "adSet": {
    "mode": "perUpload",
    "namePattern": "Ad Set {index:01}",
    "targetingPerAdSet": {
      "Ad Set 02": { "countries": ["CA"], "genders": "women" },
      "Ad Set 01": { "countries": ["GB"] }
    }
  }
}

No modo personalizado, groups[].targeting continua válido e mantém a substituição ao lado do grupo de mídia:

{
  "adSet": {
    "mode": "custom",
    "groups": [{
      "name": "Canada Women",
      "media": ["canada.jpg"],
      "targeting": { "countries": ["CA"], "genders": "women" }
    }]
  }
}

Regras de segmentação:

• Idade e gênero precisam ser ativados. Defina ageSelected: true ou genderSelected: true; caso contrário, os valores de idade ou gênero são ignorados.
• A segmentação detalhada substitui, não mescla. detailedTargetingGroups vira o público detalhado completo, então tudo o que você deixar de fora é removido.
• O raio de cidade fica entre 10 e 50 milhas, ou entre 17 e 80 quilômetros. Um valor fora dessa faixa é movido para o limite mais próximo, e um raio ausente usa o mínimo.

Use ads targeting:search para encontrar a key da cidade (tipo city), a key do CEP, como US:90210 (tipo zip), e o id, o name e o type de cada seleção detalhada (tipo detailed). Omita países, cidades e CEPs para herdar os locais de origem. Países, cidades e CEPs são combinados como alternativas, então adicionar Austin ou um CEP a countries: ["US"] continua segmentando os Estados Unidos inteiros; omita os países para segmentar só a cidade ou o CEP. CEPs não têm raio.

Configuração de texto

Texto comum aplica o mesmo texto a todos os anúncios:

{
  "texts": {
    "common": {
      "headlines": ["Headline 1", "Headline 2"],
      "bodies": ["Primary text"],
      "descriptions": ["Description"]
    },
    "strategy": "flexible"
  }
}

Texto por anúncio permite definir um texto único para cada arquivo:

{
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Hero Headline"],
        "bodies": ["Hero copy"],
        "descriptions": ["Hero desc"],
        "cta": "LEARN_MORE",
        "link": "https://example.com/hero",
        "urlTags": "utm_content=hero"
      },
      "banner.jpg": {
        "headlines": ["Banner Headline"],
        "bodies": ["Banner copy"]
      }
    }
  }
}

As chaves por anúncio são nomes de arquivo (não caminhos completos). Cada entrada aceita: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Os campos que você não informar são herdados do anúncio modelo.

Texto por conjunto de anúncios aplica um bloco de texto a todos os anúncios de um conjunto de anúncios de destino. Use um nome ou ID simples de conjunto de anúncios quando ele for único, ou uma entrada campaign::key quando o mesmo nome de conjunto aparecer em mais de uma campanha:

{
  "texts": {
    "perAdset": {
      "Prospecting::prospecting_set": {
        "headlines": ["Prospecting headline"],
        "bodies": ["Prospecting copy"],
        "descriptions": ["Prospecting description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/prospecting",
        "displayUrl": "example.com/prospecting",
        "urlTags": "utm_campaign=prospecting",
        "aiDisclosure": false
      }
    }
  }
}

Cada chave de texts.perAdset precisa corresponder a um conjunto de anúncios planejado. Chaves sem correspondência são rejeitadas, em vez de cair no texto comum.

Presets de texto permitem carregar uma configuração de texto salva:

{ "textPresetId": "preset_id_here" }

Você não pode combinar textPresetId com texts.

Divulgação de IA

Declare que o criativo de um anúncio foi feito ou editado de forma significativa com IA (a autodeclaração de conteúdo de IA da Meta). Se você omitir, vale o anúncio do qual você copia as configurações: a declaração dele é mantida, como no Uploader. Defina false para desativar.

{ "aiDisclosure": true }

O campo aiDisclosure de nível superior (ou a flag --ai-disclosure) vale para todos os anúncios do lançamento. Você também pode definir aiDisclosure como true ou false em uma entrada de texts.perAd ou texts.perAdset; esse valor por entrada sempre vence, incluindo um false explícito.

As opções de estratégia controlam como várias variações de texto são tratadas:

• "flexible" (padrão) deixa a Meta otimizar entre as suas variações de texto. Vários títulos e textos viram opções que o Facebook combina entre si.
• "separate" cria um anúncio separado para cada combinação de texto.

CTA e links

Um CTA de nível superior vale para todos os anúncios. CTAs por anúncio em texts.perAd e CTAs por conjunto de anúncios em texts.perAdset têm prioridade sobre ele.

{
  "cta": {
    "type": "SHOP_NOW",
    "link": "https://example.com",
    "displayUrl": "example.com"
  },
  "urlTags": "utm_source=facebook&utm_medium=paid"
}

Tipos de CTA padrão: LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, GET_OFFER, GET_QUOTE, CONTACT_US, GET_IN_TOUCH, BOOK_TRAVEL (mostrado como Book Now), ORDER_NOW, BUY_NOW, APPLY_NOW, DOWNLOAD, SEE_DETAILS, WATCH_MORE, LISTEN_NOW, PLAY_GAME, DONATE_NOW, OPEN_LINK

Use o valor da Meta (como SHOP_NOW), e não o rótulo do botão.

CTAs específicos de objetivo são herdados do anúncio modelo e não devem ser definidos manualmente. Defini-los no tipo errado de campanha causa um erro da API do Facebook.

Teste de URL (Split Destination)

Informe de 2 a 5 URLs de destino em texts.urlVariants e cada conjunto de anúncios gerado é duplicado uma vez por URL, para que a Meta otimize cada combinação de anúncio e landing page de forma independente.

{
  "texts": {
    "common": { "headlines": ["Hero"], "bodies": ["Copy"] },
    "urlVariants": [
      { "link": "https://example.com/homepage", "label": "homepage" },
      { "link": "https://example.com/quiz", "label": "quiz-v2" }
    ]
  }
}

• label é opcional. Quando omitido, é usado o último trecho do caminho da URL (/quiz-v2 vira quiz-v2), ou o nome do host para URLs da raiz.
• No modo de um único conjunto de anúncios, o rótulo de cada variante vira o nome completo do conjunto de anúncios.
• Nos modos perUpload e autoGroup, o nome de cada conjunto de anúncios duplicado ganha _{label} no final (por exemplo Ad Set 01_quiz-v2), ou o rótulo substitui um token {destination} se você incluir um.
• O token {date} em um rótulo vira a data de hoje (por exemplo, launch-{date} vira launch-2026-04-27).
• Cada URL de destino precisa ser única. URLs idênticas (ou variações da mesma URL com barra no final ou maiúsculas diferentes) viram uma só entrada, então garanta que você tem pelo menos 2 destinos diferentes.
• O orçamento do seu conjunto de anúncios é multiplicado pelo número de variantes, já que cada cópia é um conjunto de anúncios próprio.
• Não é compatível com anúncios de origem com destino especial (formulário de leads, Messenger, WhatsApp, Direct do Instagram, ligação). A CLI rejeita essa combinação com um erro claro, porque esses formatos não usam cta.link.
• Substituições de link por anúncio em texts.perAd perdem para a URL da variante quando os dois estão definidos.

Aprimoramentos criativos

Controle os aprimoramentos criativos Advantage+:

{ "creativeEnhancements": "none" }

Recursos disponíveis: text_translation, inline_comment, enhance_cta, text_optimizations, reveal_details_over_time, show_destination_blurbs, image_brightness_and_contrast, image_touchups, video_auto_crop, video_filtering, pac_relaxation, image_animation, image_templates, adapt_to_placement, product_extensions, product_tags, description_automation, add_text_overlay, music, carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized

A chave show_destination_blurbs aparece como Show spotlights, e pac_relaxation como Flex media.

Os formatos de exibição são copiados do anúncio de origem por padrão, mesmo com uma lista de recursos, "none" ou { "useMetaDefaults": false }. Para desativar um ou ambos, use creativeEnhancements.excludedFormats com "format_carousel" (Show as carousel) e/ou "format_collection" (Show as collection), ou defina o formato como false em um objeto por recurso. Omita excludedFormats para manter ambos. Cada formato excluído precisa existir na origem e poder ser copiado; formatos baseados em catálogo exigem um catálogo associado. IDs desconhecidos, valores que não sejam arrays, ativar e excluir o mesmo ID e usar excludedFormats em criativos de publicações existentes são rejeitados. Não é possível ativar formatos ausentes na origem.

Ao escolher recursos um a um, liste só os que fazem sentido para o tipo de mídia. Os recursos de vídeo (video_auto_crop, video_filtering) só valem para anúncios em vídeo. Os recursos de carrossel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) só valem para anúncios em carrossel.

product_tags vale para anúncios de imagem e de vídeo e só funciona por clonagem. Ele só pode ser ativado quando o anúncio de origem tem um catálogo associado e marcações de produto explícitas com posição; todas as marcações de origem e as posições delas são preservadas. "all" só o inclui para uma origem elegível e nunca inventa uma marcação de produto.

Carousel Ads

Agrupe arquivos enviados em anúncios em carrossel, com texto por card e um texto geral opcional para o carrossel. cardTexts controla os cards individuais. O texto geral do carrossel pode ficar no próprio objeto do carrossel ou em texts.perAd, usando o name do carrossel; os campos no próprio objeto vencem quando os dois existem.

{
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
      "headlines": ["Overall Carousel Headline"],
      "bodies": ["Overall primary text"],
      "descriptions": ["Overall description"],
      "cta": "SHOP_NOW",
      "link": "https://example.com/carousel",
      "urlTags": "utm_content=my_carousel",
      "cardTexts": [
        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
      ]
    }
  ]
}

Formato alternativo para o texto geral:

{
  "texts": {
    "perAd": {
      "My Carousel": {
        "headlines": ["Overall Carousel Headline"],
        "bodies": ["Overall primary text"],
        "descriptions": ["Overall description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/carousel",
        "urlTags": "utm_content=my_carousel"
      }
    }
  },
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"]
    }
  ]
}

Os cards precisam referenciar nomes de arquivo do lote de upload ou da mídia capturada em um build salvo. Cada carrossel precisa de 2 a 10 cards. Os arquivos usados em um carrossel são removidos da lista de anúncios padrão.

Flexible Ads

Agrupe vários ativos em um único anúncio flexível, em que a Meta escolhe o melhor ativo para cada posicionamento:

{
  "flexible": [
    {
      "name": "Multi-Asset Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"]
    }
  ]
}

Cada grupo flexível precisa de 2 a 10 ativos. Os arquivos usados em um grupo flexível são removidos da lista de anúncios padrão.

A Meta não oferece anúncios flexíveis em campanhas de Leads. Um grupo flexível copiado de um anúncio de uma campanha de Leads é recusado com FLEXIBLE_OBJECTIVE_UNSUPPORTED na pré-visualização, ao salvar e ao criar, antes de qualquer coisa ser criada. Use anúncios padrão ou Multi Media nesse caso, ou copie de um anúncio de uma campanha de Sales.

Multi Media Ads

Agrupe de 2 a 10 imagens ou vídeos enviados em um anúncio Multi Media da Meta:

{
  "multimedia": [
    {
      "name": "Mixed Media Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"],
      "assetTexts": [
        {
          "headline": "Hero headline",
          "primaryText": "Hero primary text",
          "description": "Hero description",
          "link": "https://example.com/hero",
          "displayUrl": "example.com/hero"
        }
      ]
    }
  ]
}

Os ativos precisam referenciar nomes de arquivo do lote de upload ou da mídia capturada em um build salvo. assetTexts é opcional e se alinha com assets pelo índice; cada campo é uma substituição única para aquele ativo, e campos em branco usam o texto e as URLs principais do anúncio. O texto e a URL principais do anúncio valem para todos os ativos, e a substituição de um ativo, incluindo o primeiro, muda só esse ativo. Vídeos precisam de uma URL pública de thumbnail capturada e em cache. Os arquivos usados em um grupo Multi Media são removidos da lista de anúncios padrão.

Nomes de anúncios

Personalize como seus anúncios são nomeados:

{ "adNamePattern": "{filename} - {date}" }

As transformações envolvem um valor. Um valor vazio significa o nome do arquivo:

As transformações podem ser aninhadas, por exemplo {titlecase:{split:_:2}}. Um padrão pode ter até 200 caracteres. Veja Padrões de nome de anúncios para mais exemplos.

Opções

{
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet",
    "schedule": {
      "startTime": "2026-04-01T09:00:00",
      "endTime": "2026-04-30T23:59:59"
    }
  }
}

Quando os anúncios vão para um conjunto de anúncios existente, options.schedule só funciona em campanhas de Sales e App promotion, porque a Meta só suporta agendamento por anúncio nesses objetivos. Para outros objetivos, crie um novo conjunto de anúncios ou remova options.schedule.

Limites da especificação

Upload e detecção de variantes

Os grupos de variantes são detectados automaticamente pelas convenções de nome dos arquivos, igual ao app web. Veja Variações de proporção para todos os detalhes sobre as convenções de nome.

Sufixos de proporção: hero_1x1.jpg + hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg + hero_1.91x1.jpg são agrupados como um único anúncio com variantes. Até 5 proporções por grupo.

Posição do token: o token de proporção pode aparecer no final (hero_4x5.jpg), no meio (hero_4x5_v2.jpg) ou no início (4x5_hero.jpg).

Sufixos legados em palavras: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg ainda funcionam e correspondem a 9x16 e 16x9.

O delimitador padrão é _. Você pode mudá-lo (ou aceitar mais de um) em Account > Defaults > Placements > Filename Separator.

Padrões comuns

Subir e criar com um preset

ads upload ./creatives/hero.jpg ./creatives/banner.jpg
ads create:preview spec.json
ads create spec.json

Em que spec.json contém:

{ "adPresetId": "PRESET_ID", "uploadId": "BATCH_ID" }

Copiar as configurações de um anúncio existente

Navegue pela sua conta para encontrar o anúncio:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Depois, crie uma especificação que aponte para ele:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "BATCH_ID"
}

O anúncio de origem pode ter configurações de criativo próprias ou ter sido feito a partir de uma publicação existente de uma Página, da qual o link, o botão e o texto são copiados. Anúncios de formulário, de ligação e de conversa não precisam de link. Nos outros, se nem o anúncio nem a publicação dele tiverem link para um site, defina cta.link. Caso contrário, a prévia e a criação são recusadas com um 400 antes de qualquer coisa ser criada. A CLI rejeita um anúncio sem configurações de criativo para copiar antes de enviar o pedido de criação.

Salvar um API preset a partir de um anúncio existente

ads presets:save --from-ad 120233848667930472 --name "Spring Purchase Template"
ads create --preset PRESET_ID --upload BATCH_ID

Isso salva um API preset no mesmo formato usado pelo app web. O anúncio de origem precisa ter configurações de criativo próprias; anúncios baseados em publicações de Página não podem ser salvos como API presets.

Texto por anúncio, com um texto único para cada arquivo

{
  "adPresetId": "PRESET_ID",
  "uploadId": "BATCH_ID",
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Summer Sale Now On"],
        "bodies": ["Save up to 50% on all items"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/summer"
      },
      "banner.jpg": {
        "headlines": ["New Collection Available"],
        "bodies": ["Browse our latest styles"],
        "cta": "LEARN_MORE",
        "link": "https://example.com/new"
      }
    }
  }
}

Agrupar automaticamente em vários conjuntos de anúncios

{
  "adPresetId": "PRESET_ID",
  "uploadId": "BATCH_ID",
  "adSet": { "mode": "autoGroup", "adsPerAdSet": 3 }
}

Observações importantes

1. Sempre veja a prévia primeiro. create:preview pega erros de configuração antes de mexer no Facebook.
2. Os anúncios são ativos por padrão. Use --status PAUSED ou "status": "PAUSED" na especificação para criá-los pausados.
3. O uploadId vem da saída do upload. É o ID de lote retornado por ads upload.
4. Os uploads ficam presos a uma conta de anúncio. Os arquivos sobem direto para a biblioteca de mídia do Facebook da conta selecionada. O ID de lote só pode ser usado com a mesma conta.
5. copyFromAd precisa de mídia que possa ser encontrada. Informe uploadId, ou lance um build salvo cujas imagens capturadas têm mediaHash e cujos vídeos têm mediaId. Opcionalmente, informe campaign.id e adSet.id para controlar para onde os anúncios vão.
6. As chaves de texto por anúncio são nomes de arquivo. Use "hero.jpg", e não "/path/to/hero.jpg".
7. textPresetId e texts são mutuamente exclusivos. Use um ou outro, não os dois.
8. CTAs específicos de objetivo são herdados do modelo. Não defina MESSAGE_PAGE, WHATSAPP_MESSAGE etc. manualmente.

Anúncios de parceria com a sua própria mídia

A CLI e o MCP podem lançar anúncios de parceria com mídia enviada no Facebook e no Instagram. Use sua especificação normal de mídia de imagem ou vídeo, carrossel, flexível, Multi Media ou variante de posicionamento e adicione profile.partnership.enabled: true. A mídia enviada segue a montagem comum, com uma Second Identity. Omita uploaderMode ou defina como false; true seleciona publicações importadas e não pode ser usado com uploads.

Escolha sua First Identity com profile.pageId e profile.instagramId. O parceiro compartilhado é a Second Identity:

{
  "accountId": "act_123",
  "copyFromAd": "SOURCE_AD_ID",
  "adSet": { "id": "EXISTING_AD_SET_ID" },
  "mediaItems": [
    { "mediaName": "one.jpg", "mediaType": "image", "mediaHash": "UPLOADED_IMAGE_HASH_ONE" },
    { "mediaName": "two.jpg", "mediaType": "image", "mediaHash": "UPLOADED_IMAGE_HASH_TWO" }
  ],
  "profile": {
    "pageId": "111",
    "instagramId": "222",
    "partnership": {
      "enabled": true,
      "sponsorPageId": "333",
      "sponsorInstagramId": "444",
      "displayMode": "both"
    }
  },
  "options": { "status": "PAUSED" }
}

Para parceiros diferentes por anúncio, adicione este bloco texts à mesma especificação. A segunda linha usa No Partner de forma explícita:

{
  "texts": {
    "mode": "perAd",
    "perAd": {
      "one.jpg": { "sponsorPageId": "555", "sponsorInstagramId": "666" },
      "two.jpg": { "sponsorPageId": null, "sponsorInstagramId": null }
    }
  }
}

Para escopos por conjunto de anúncios, use texts.mode: "perAdset" e texts.perAdset, com chaves pelo nome ou ID final do conjunto de anúncios ou por campaign::key. Em lançamentos com várias campanhas, use profile.campaigns[<id or unambiguous name>] para substituir o patrocinador por campanha. A ordem de resolução é: parceiro compartilhado, depois campanha, depois a linha ativa. Campos de patrocinador omitidos são herdados de forma independente; defina explicitamente os dois IDs como null para No Partner. Trocar só a Página do parceiro não limpa um ID do Instagram herdado na mídia enviada; defina esse ID explicitamente quando mudar o par. Os campos de First Identity da linha (pageId, instagramId, threadsId) continuam independentes.

Para uma Second Identity só no Instagram, defina sponsorPageId: null, sponsorInstagramId com o ID da conta aprovada e sponsorPageUseInstagramAccount: true. Uma Página do Facebook do parceiro também é suportada para mídia enviada. A restrição às importações de publicações do Facebook não vale para mídia enviada.

displayMode vale para todo o lançamento: both (padrão), first ou dynamic. Cada parceiro efetivo precisa ser diferente da First Identity. Como no Uploader, um parceiro com aprovação pendente, ou que ainda não aprovou anúncios de parceria para esta First Identity, não bloqueia o lançamento: a prévia e a criação retornam um aviso PARTNERSHIP_APPROVAL_PENDING com o nome do parceiro, e a Meta pode criar os anúncios com veiculação pendente até o parceiro aprovar. Cada linha precisa de um parceiro completo, herdado ou explícito, ou de uma substituição explícita No Partner. Ativar parcerias sem nenhum patrocinador é recusado. A aprovação é verificada de novo na prévia e na criação; um build salvo não guarda concessões de permissão.

ads create:preview e ads_preview mostram o parceiro efetivo, a aprovação e o modo de cabeçalho de cada anúncio, agrupados por conjunto de anúncios. Builds de parceria com mídia enviada completos e salvos na web podem ser lançados pela CLI e pelo MCP; builds editados por essas ferramentas restauram Partnership Ads, as identidades, os parceiros por linha e o modo de cabeçalho no uploader web.

Especificação de parceria com publicação existente do Instagram

As especificações JSON da CLI e as ferramentas MCP ads_preview / ads_create aceitam publicações do Instagram com mediaItems[].kind: "partnershipPost". O anúncio de origem ou o preset fornece as configurações; a publicação importada fornece a identidade fixa do criador e a legenda orgânica. Escolha o patrocinador compartilhado em profile.partnership, ou defina o patrocinador e substituições opcionais de texto em texts.perAdset ou texts.perAd. Título, CTA, URL do site e depoimento podem ficar vazios. Um CTA preenchido precisa de uma URL do site. Importações de publicações do Facebook não são suportadas.

A prévia verifica o conteúdo e as permissões com chamadas de leitura e só de validação da Meta, sem criar anúncios nem guardar códigos. O resolvedSpec dela, sem códigos, pode ser salvo, mas os códigos precisam ser informados de novo na criação. A criação verifica a permissão de novo.

Use mediaItems[].kind: "partnershipPost" com platform: "instagram". Escolha exatamente um localizador: sourceInstagramMediaId, import.postUrl ou import.instagramShortcode. Um import.adCode correspondente pode acompanhar um localizador, ou ser usado sozinho. O anúncio de origem ou o preset fornece as configurações, não a publicação. Os campos opcionais creator.pageId e creator.instagramId confirmam o criador resolvido.

{
  "accountId": "act_123",
  "copyFromAd": "456",
  "adSet": { "mode": "single", "id": "789" },
  "mediaItems": [{ "kind": "partnershipPost", "mediaName": "creator-post-one", "platform": "instagram", "import": { "postUrl": "https://www.instagram.com/p/POST_SHORTCODE/" } }],
  "profile": { "partnership": { "enabled": true, "uploaderMode": true, "sponsorPageId": "111", "sponsorInstagramId": "222", "displayMode": "both" } },
  "texts": { "mode": "common", "common": { "headline": "Discover the collection", "callToAction": "LEARN_MORE", "link": "https://example.com/", "multiAdvertiserAds": false } },
  "options": { "status": "PAUSED", "pauseAt": "ad" }
}

Para uma importação só com código, use este corpo de requisição completo, com os seus IDs e um código inserido por um gerador de segredos em memória. Não salve o código real em um arquivo:

{
  "accountId": "act_123",
  "copyFromAd": "456",
  "adSet": { "mode": "single", "id": "789" },
  "mediaItems": [{ "kind": "partnershipPost", "mediaName": "creator-post-one", "platform": "instagram", "import": { "adCode": "REPLACE_IN_MEMORY" } }],
  "profile": { "partnership": { "enabled": true, "uploaderMode": true, "sponsorPageId": "111", "sponsorInstagramId": "222", "displayMode": "both" } },
  "texts": { "mode": "common", "common": { "headline": "Discover the collection", "callToAction": "LEARN_MORE", "link": "https://example.com/", "multiAdvertiserAds": false } },
  "options": { "status": "PAUSED", "pauseAt": "ad" }
}

Use de 1 a 250 publicações por requisição, cada uma com um mediaName único de no máximo 200 caracteres. sponsorPageId precisa corresponder a uma Página do Facebook real da marca em todos os anúncios planejados; sponsorInstagramId é opcional. O displayMode do cabeçalho vale para todo o lançamento: both, first ou dynamic. Para publicações importadas, first significa o cabeçalho só com o criador, chamado Partner identity only in the header no uploader, e não um cabeçalho só com a marca.

Patrocinadores por campanha usam profile.campaigns, com chaves pelo ID da campanha ou por um nome de campanha sem ambiguidade, com sponsorPageId e, opcionalmente, sponsorInstagramId. A ordem de resolução é: patrocinador compartilhado, depois campanha, depois a substituição ativa por conjunto de anúncios ou por anúncio. Coloque os campos de patrocinador compartilhado em profile.partnership, nunca em texts.common; um adCode fica no import da linha ou em um bloco ativo por anúncio ou por conjunto de anúncios. Os valores pageId / instagramId do criador são confirmações, não uma forma de mudar o autor da publicação.

multiAdvertiserAds é true por padrão; defina explicitamente como false para desativar. Os valores de CTA precisam ser enums da Meta, como SHOP_NOW ou LEARN_MORE, e não rótulos como Shop Now, e um CTA preenchido exige um destino http:// ou https://. A legenda orgânica não pode ser editada. Os blocos de texto de publicações importadas aceitam um título, CTA, link, tags de URL, depoimento, divulgação de IA e a escolha de multi-anunciante. Cada mapa de substituição por anúncio ou por conjunto de anúncios aceita no máximo 200 entradas.

Para publicações importadas, a CLI e o MCP rejeitam importações de publicações do Facebook, lotes que misturam publicações importadas e mídia enviada, estruturas de carrossel, flexíveis ou Multi Media, agrupamento por variação de posicionamento e identidades do Threads. A mídia enviada suporta os formatos criativos normais e parceiros por linha. Novas importações de publicações do Facebook também não são suportadas no uploader web no momento. Não existe um navegador de publicações aprovadas no uploader; importe uma URL, um ID de publicação ou um código autorizado do Instagram.

Para texts.mode: "perAd", use mediaName como chave de texts.perAd. Para texts.mode: "perAdset", use o nome ou ID final do conjunto de anúncios ou campaign::key como chave de texts.perAdset. O texto compartilhado usa texts.common. adSet.groups[].media contém esses nomes de mídia; reutilize uma linha de mídia entre grupos em vez de importar a mesma origem duas vezes.

Use ads create:preview /dev/stdin --account act_123 para a prévia e depois ads create /dev/stdin --account act_123 --status PAUSED para criar. Passe códigos sensíveis só pelo stdin, nunca como argumentos, query strings ou em um arquivo salvo no disco. Informe os códigos de novo na criação; builds salvos e a saída da prévia não os incluem. Use --account ou rode ads account act_123 antes, mesmo quando o JSON contém accountId.

Product Showcase

Product Showcase mostra produtos de um catálogo sob um anúncio com uma única imagem ou um único vídeo. Os anúncios de catálogo completo (dinâmicos/DPA) ainda não são suportados.

Os IDs devem ser cadeias de dígitos. As recomendações exigem campanhas de Vendas (OUTCOME_SALES); a seleção manual de catálogo e conjunto também funciona com outros objetivos. Product Showcase não pode ser ativado em carrosséis, formatos flexíveis, multimédia, publicações existentes ou anúncios Partnership.

Consulte catálogos e conjuntos e peça uma recomendação:

ads catalogs list --account act_123
ads catalogs product-sets 3390205374500501 --product-set 29588799347389253 --json
ads catalogs recommend --url https://www.asphaltgold.com/collections/nike-sneaker --page 1234 --pixel 5678
ads create:preview spec.json --product-showcase recommended
ads create spec.json --product-showcase on --catalog 3390205374500501 --product-set 29588799347389253
ads create:preview spec.json --product-showcase off

Create e Preview aceitam productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled é true por predefinição. Omitir o campo mantém o criativo de origem. RECOMMENDED usa a escolha Meta (choiceSource: "DEFAULT"); MUST_PICK exige um ID candidato como productSetId ("MANUAL"). MANUAL exige catálogo e conjunto. Uma escolha diferente validada usa "MANUAL".

Opções Create e Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Apenas IDs significa on; recommended define useRecommendation: true. Off define { enabled: false }, não aceita IDs e mantém o conjunto do anúncio de origem.

Preview devolve productShowcase com enabled, IDs, nome opcional, choiceSource e source (recommendation, manual, source_ad), ou null. As recomendações são só de leitura. Test Mode exige IDs quando ativado, não consulta catálogos e indica que não foram verificados. As escolhas guardadas na interface são convertidas; as predefinições são verificadas novamente no lançamento.