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.

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 (e para o ads create:test, exclusivo para administradores). Você pode usá-las no lugar de um arquivo de especificação, ou junto com ele.

Flags de duplicação por Post ID

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 e o Test Mode da web leem 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). Vem desativado por padrão e nunca é ativado automaticamente.

{ "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.

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.

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 ativo principal exibido usa o texto e a URL principais do anúncio, e qualquer texto que substitua o do ativo principal vira a primeira opção de texto principal. 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 precisa ter configurações de criativo próprias. Se ele foi feito a partir de uma publicação existente de uma Página, a CLI o rejeita 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 e ter acesso aprovado para anúncios de parceria. Aprovação pendente ou ausente é recusada, com a identidade indicada. 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. O ads create:test, exclusivo para administradores, ou ads_create com options.testMode: true validam as chamadas elegíveis com a Meta sem criar anúncios e informam as contagens de aprovadas, reprovadas e não verificadas. 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.

Administradores podem rodar ads create:test /dev/stdin --account act_123 --status PAUSED. Ele não cria anúncios na Meta e informa as chamadas metaValidation como aprovadas, reprovadas ou não verificadas. Uma recusa da Meta sai com código 1. Chamadas que precisam de IDs simulados não são verificadas; uma validação aprovada não garante veiculação nem aparência. O Test Mode pode salvar códigos de autorização criptografados e registros de lançamento.