Anuncios con video desde un agentepublica en Meta un video que está en tu disco

01 el punto de partida

Por qué un agente no puede subir el video directo

Meta tiene dos formas de recibir un video para anuncios: el archivo como form data en el campo source, o una URL en file_url que sus servidores descargan. La primera exige que quien hace la llamada tenga el binario en memoria y mande multipart (o un upload por trozos con upload_phase start/transfer/finish). Un agente que opera desde un chat no está en esa posición: sus herramientas mandan JSON y texto, y el MCP oficial de Meta Ads expone solo la variante por URL.

02 la alternativa oficial

La CLI de Meta sí sube video local (con dos huecos)

Desde abril de 2026 Meta publica una CLI oficial dentro de lo que llama Ads AI Connectors: el paquete meta-ads en PyPI, escrito en Python (necesita 3.12 o 3.13; con 3.14 no hay wheel y pip te dice que no existe). La instalé en una carpeta aislada y revisé sus comandos uno por uno. Lo relevante para esta guía: meta ads creative create acepta --video con una ruta de tu disco y sube el binario por trozos usando el SDK facebook-business que trae adentro. Es decir, el muro de la sección anterior lo tiene el agente en chat, no la API.

python3.13 -m venv .venv && . .venv/bin/activate && pip install meta-ads && meta --version

export ACCESS_TOKEN=... AD_ACCOUNT_ID=act_XXXXXXXX && meta auth status && meta ads creative create --name 'hook-testimonio' --video ./video.mp4 --page-id PAGE_ID --body 'Texto principal' --title 'Título' --link-url https://tu-landing.com/evento --call-to-action LEARN_MORE

meta ads ad create ADSET_ID --name 'hook-testimonio' --creative-id CREATIVE_ID

Los dos huecos los vi leyendo lo que la CLI manda, con el SDK simulado para no gastar en una cuenta real. Uno: pide el creativo inmediatamente después de subir el video, sin esperar a que status.video_status sea ready. Dos: el video_data que construye lleva video_id, message, title y call_to_action, pero ningún image_url ni image_hash. Son exactamente los dos primeros errores de la tabla de más abajo. No corrí el flujo contra una cuenta real, así que no te digo que falle siempre; te digo que, si te falla con 'video inválido' o pidiéndote imagen, ya sabes por qué, y que el escape es --object-story-spec @oss.json con tu propio video_data (con image_hash de adimages) una vez que el video esté ready.

03 el patrón

El bucket puente

Un bucket de Supabase Storage dedicado solo a esto, en un proyecto que no toque nada sensible. En el caso real se creó en un proyecto de utilidades aparte del CRM de producción, precisamente para que la llave que se compartiera con el equipo no pudiera leer ninguna tabla con datos de clientes. Decisiones que quedaron fijas:

Sobre el borrado: el CDN de Supabase puede seguir sirviendo el archivo unos minutos después del DELETE. El objeto sí está borrado (compruébalo en storage.objects, no abriendo la URL). No es un bug tuyo.

npx supabase storage buckets create puente-anuncios --private --file-size-limit 500MB --allowed-mime-types 'video/*,image/*'

04 de disco a anuncio

El flujo completo, paso a paso

1. Subir el video (y el thumbnail) al bucket privado con la llave de servicio desde tu script, nunca desde el navegador.
2. Generar una URL firmada de 3600 segundos para cada archivo con createSignedUrl.
3. POST act_{cuenta}/advideos con file_url = la URL firmada y title. La respuesta trae el id del video.
4. Hacer poll a GET /{video_id}?fields=status cada 5 segundos hasta que status.video_status sea ready. Si es error, abortar y borrar del bucket.
5. POST act_{cuenta}/adcreatives con object_story_spec: page_id y video_data con video_id, image_url (thumbnail), message, title y call_to_action.
6. POST act_{cuenta}/ads con name, adset_id, creative: { creative_id } y status: PAUSED.
7. Borrar los dos objetos del bucket. Reportar IDs. Una persona revisa en Ads Manager y activa.

Los pasos 4 y 5 son donde se atora la gente. Meta acepta la llamada a advideos en un segundo, pero el video tarda entre 20 segundos y varios minutos en procesarse. Crear el creativo antes de eso falla, y el mensaje de error no dice 'espera': dice que el video no es válido.

05 para copiar

El script TypeScript completo

Un solo archivo, se corre con tsx. Lee credenciales del entorno, nunca del código. La cuenta publicitaria se pasa siempre explícita: en el caso real el negocio tenía más de treinta cuentas act_ distintas por producto y ciudad, y un default habría creado anuncios en la cuenta equivocada sin que nadie lo notara.

npm i @supabase/supabase-js && npm i -D tsx typescript @types/node

ffmpeg -y -ss 00:00:01 -i ./video.mp4 -vframes 1 -q:v 2 ./thumb.jpg

ffmpeg -y -i ./original.mov -c:v libx264 -preset medium -crf 20 -pix_fmt yuv420p -c:a aac -b:a 160k -movflags +faststart ./video.mp4

git clone https://github.com/davidiriza-lab/meta-ads-video-agente.git

import { readFile } from "node:fs/promises";
import { basename } from "node:path";
import { createClient } from "@supabase/supabase-js";

// ---------- configuración (todo por entorno, nada en el código) ----------
const GRAPH = "https://graph.facebook.com/v21.0";
const BUCKET = "puente-anuncios";
const SIGNED_URL_TTL = 3600; // segundos

function env(nombre: string): string {
  const v = process.env[nombre];
  if (!v) throw new Error(`Falta la variable ${nombre}`);
  return v;
}

const META_TOKEN = env("META_SYSTEM_USER_TOKEN");
const supabase = createClient(env("SUPABASE_URL"), env("SUPABASE_SERVICE_ROLE_KEY"));

interface Entrada {
  cuenta: string;      // "act_123..." — siempre explícita, sin default
  adsetId: string;
  pageId: string;
  videoPath: string;
  thumbPath: string;
  nombre: string;      // nombre del anuncio y del video en biblioteca
  mensaje: string;     // texto principal
  titulo: string;
  link: string;        // destino del CTA
}

// ---------- helpers Graph API ----------
interface MetaError { error?: { message: string; code?: number; error_subcode?: number } }

export async function graphPost<T>(path: string, body: Record<string, string>): Promise<T> {
  const res = await fetch(`${GRAPH}/${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ ...body, access_token: META_TOKEN }),
  });
  const data = (await res.json()) as T & MetaError;
  if (data.error) {
    if (data.error.code === 17) {
      // rate limit: esperar y reintentar una vez, nunca en loop agresivo
      await new Promise((r) => setTimeout(r, 75_000));
      return graphPost<T>(path, body);
    }
    throw new Error(`Meta ${path}: ${data.error.message}`);
  }
  return data;
}

async function graphGet<T>(path: string, fields: string): Promise<T> {
  const url = `${GRAPH}/${path}?fields=${fields}&access_token=${encodeURIComponent(META_TOKEN)}`;
  const data = (await (await fetch(url)).json()) as T & MetaError;
  if (data.error) throw new Error(`Meta ${path}: ${data.error.message}`);
  return data;
}

// ---------- paso 1 y 2: bucket + URL firmada ----------
async function subirYFirmar(localPath: string, contentType: string, prefijo: string): Promise<{ objeto: string; url: string }> {
  const objeto = `${prefijo}-${Date.now()}-${basename(localPath)}`;
  const bytes = await readFile(localPath);

  const up = await supabase.storage.from(BUCKET).upload(objeto, bytes, { contentType, upsert: false });
  if (up.error) throw new Error(`Upload ${objeto}: ${up.error.message}`);

  const firmada = await supabase.storage.from(BUCKET).createSignedUrl(objeto, SIGNED_URL_TTL);
  if (firmada.error || !firmada.data) throw new Error(`Firma ${objeto}: ${firmada.error?.message ?? "sin data"}`);

  return { objeto, url: firmada.data.signedUrl };
}

async function borrar(objetos: string[]): Promise<void> {
  if (objetos.length === 0) return;
  const { error } = await supabase.storage.from(BUCKET).remove(objetos);
  if (error) console.warn("No se pudo borrar del bucket:", error.message);
}

// ---------- paso 4: esperar a que Meta termine de procesar ----------
interface VideoStatus { status?: { video_status?: "ready" | "processing" | "error"; processing_progress?: number } }

async function esperarVideoListo(videoId: string, maxMs = 10 * 60_000): Promise<void> {
  const inicio = Date.now();
  while (Date.now() - inicio < maxMs) {
    const v = await graphGet<VideoStatus>(videoId, "status");
    const estado = v.status?.video_status ?? "processing";
    if (estado === "ready") return;
    if (estado === "error") throw new Error(`Meta no pudo procesar el video ${videoId}`);
    console.log(`  procesando... ${v.status?.processing_progress ?? 0}%`);
    await new Promise((r) => setTimeout(r, 5_000));
  }
  throw new Error(`Timeout esperando el video ${videoId}`);
}

// ---------- flujo ----------
export async function publicarVideo(e: Entrada): Promise<{ videoId: string; creativeId: string; adId: string }> {
  const subidos: string[] = [];
  try {
    console.log("1/6 subiendo al bucket puente...");
    const video = await subirYFirmar(e.videoPath, "video/mp4", "ad");
    const thumb = await subirYFirmar(e.thumbPath, "image/jpeg", "thumb");
    subidos.push(video.objeto, thumb.objeto);

    console.log("2/6 Meta descarga el video (advideos)...");
    const av = await graphPost<{ id: string }>(`${e.cuenta}/advideos`, {
      file_url: video.url,
      title: e.nombre,
    });

    console.log("3/6 esperando status.video_status = ready...");
    await esperarVideoListo(av.id);

    console.log("4/6 creando el creativo (video_data)...");
    const creative = await graphPost<{ id: string }>(`${e.cuenta}/adcreatives`, {
      name: e.nombre,
      object_story_spec: JSON.stringify({
        page_id: e.pageId,
        video_data: {
          video_id: av.id,
          image_url: thumb.url,          // thumbnail obligatorio; URL firmada, no CDN de Meta
          message: e.mensaje,
          title: e.titulo,
          call_to_action: { type: "LEARN_MORE", value: { link: e.link } },
        },
      }),
    });

    console.log("5/6 creando el anuncio EN PAUSA...");
    const ad = await graphPost<{ id: string }>(`${e.cuenta}/ads`, {
      name: e.nombre,
      adset_id: e.adsetId,
      creative: JSON.stringify({ creative_id: creative.id }),
      status: "PAUSED",
    });

    console.log("6/6 limpiando el bucket...");
    await borrar(subidos);

    return { videoId: av.id, creativeId: creative.id, adId: ad.id };
  } catch (err) {
    await borrar(subidos); // también si falló a la mitad
    throw err;
  }
}

// ---------- uso por línea de comandos ----------
if (process.argv[1]?.endsWith("publicar-video.ts")) {
  const [cuenta, adsetId, pageId, videoPath, thumbPath, nombre] = process.argv.slice(2);
  if (!cuenta || !adsetId || !pageId || !videoPath || !thumbPath || !nombre) {
    console.error("uso: tsx scripts/publicar-video.ts act_ID ADSET_ID PAGE_ID video.mp4 thumb.jpg 'nombre'");
    process.exit(1);
  }
  publicarVideo({
    cuenta, adsetId, pageId, videoPath, thumbPath, nombre,
    mensaje: env("AD_MENSAJE"),
    titulo: env("AD_TITULO"),
    link: env("AD_LINK"),
  })
    .then((r) => console.log("Listo, todo en PAUSED:", r))
    .catch((err: unknown) => {
      console.error(err instanceof Error ? err.message : err);
      process.exit(1);
    });
}

AD_MENSAJE='Texto principal del anuncio' AD_TITULO='Título' AD_LINK='https://tu-landing.com/evento' npx tsx scripts/publicar-video.ts act_XXXXXXXX ADSET_ID PAGE_ID ./video.mp4 ./thumb.jpg 'hook-testimonio-agosto'

Dos detalles del script que no son adorno. El catch borra del bucket aunque haya fallado a la mitad: con un equipo subiendo a diario, los residuos de flujos rotos eran lo que llenaba el bucket. Y ante el código 17 de Meta (rate limit) espera 75 segundos y reintenta una vez, en vez de martillar: el día que el MCP no conectó y se usó la API directa en loop, la cuenta quedó limitada varias horas.

06 si no existe la estructura

Campaña y conjunto de anuncios, también en pausa

El script asume que ya existe un ad set. Si el agente también tiene que crear la campaña y el conjunto, el orden es campaign, adset, creative, ad, y los tres primeros se crean con status PAUSED. Un anuncio activo dentro de una campaña pausada no gasta; una campaña activa con un anuncio pausado tampoco, pero un descuido en cualquiera de los dos sí.

const campaign = await graphPost<{ id: string }>(`${cuenta}/campaigns`, {
  name: "Evento octubre — video",
  objective: "OUTCOME_LEADS",
  status: "PAUSED",
  special_ad_categories: JSON.stringify([]),
  daily_budget: "50000", // en centavos: 50000 = 500.00
});

const adset = await graphPost<{ id: string }>(`${cuenta}/adsets`, {
  name: "Evento octubre — amplio MX",
  campaign_id: campaign.id,
  status: "PAUSED",
  billing_event: "IMPRESSIONS",
  optimization_goal: "LEAD_GENERATION",
  bid_strategy: "LOWEST_COST_WITHOUT_CAP",
  targeting: JSON.stringify({ geo_locations: { countries: ["MX"] }, age_min: 25, age_max: 55 }),
  promoted_object: JSON.stringify({ page_id: pageId }),
});

// después: publicarVideo({ cuenta, adsetId: adset.id, pageId, ... })

• Presupuestos en centavos. 50000 es 500.00, no cincuenta mil. Fue la confusión más frecuente al dictarle montos a un agente; conviene que confirme el monto en pesos antes de crear.
• optimization_goal solo entre los que Meta devuelve como válidos para el objetivo; 'Performance goal isn't available' casi siempre es eso, o un promoted_object que falta.
• Para objetivos de ventas con pixel, promoted_object necesita pixel_id, y ese pixel tiene que estar compartido a la cuenta. En cuentas nuevas no lo está aunque la persona tenga permisos.
• Nunca inventes IDs de intereses. Targeting amplio por geografía, o IDs reales del buscador de targeting. Un ID inventado no falla ruidosamente: crea un ad set con targeting vacío.

07 lo que te va a pasar

Los errores reales y su arreglo

08 credenciales

System user, no token de usuario

Los tokens que obtienes iniciando sesión con tu Facebook son de usuario: el corto dura una o dos horas, el largo unos 60 días, y las docs avisan que esos plazos pueden cambiar sin previo aviso. Para un script que corre solo, o que corre un agente sin que tú estés mirando, eso es una bomba de tiempo: el flujo muere a mitad del poll. Un system user es una identidad del Business Manager pensada para servidores y software; su token se genera desde Configuración del negocio, se le asignan las cuentas publicitarias y las páginas, y no depende de que una persona siga con sesión abierta.

• Permisos mínimos para este flujo: ads_management, ads_read, business_management. Páginas e Instagram solo si vas a leer comentarios o publicar orgánico.
• Un token por uso. Generar uno nuevo no invalida los anteriores; revocar sí. En el caso real un token vivía en el CAPI de una landing en producción y otro en los scripts del equipo. Revocar 'el viejo' habría tirado la atribución de una campaña activa.
• El token nunca va en el prompt ni en un comando. En archivo con chmod 600 y leído por el script, o en variables de entorno. Cuando el equipo intentó curl con el token inline desde el agente, el clasificador de permisos lo bloqueaba; el script que lee del archivo pasa limpio.
• Herramienta indistinta. MCP oficial, token directo o una API de terceros: el criterio es no dañar la cuenta y respetar las políticas de Meta, no la herramienta. Lo que importa es el patrón (URL firmada, poll, PAUSED), no por dónde viaja la llamada.

META_SYSTEM_USER_TOKEN=EAAB...       # system user, no token de usuario
SUPABASE_URL=https://TU-PROYECTO.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...     # solo en el servidor o en tu máquina; jamás NEXT_PUBLIC_

09 la regla que no se negocia

Crear en pausa, activar con una persona

Un agente puede crear diez anuncios en un minuto. Si además los activa, en ese minuto empezó a gastar dinero de un cliente con un copy que nadie leyó, en una cuenta que quizá no era la correcta. Por eso el script no tiene parámetro para status: siempre PAUSED. Meta además manda todo anuncio nuevo a revisión (PENDING_REVIEW), así que 'activar' es una decisión humana que se toma después de ver la vista previa en Ads Manager.

PAUSED es la regla principal, pero no la única que le pongo a un agente con acceso a una cuenta publicitaria. Estas son las que quedaron en el prompt compartido del equipo, después de incidentes reales:

• Dry-run antes de crear: el agente muestra campaña, ad set, presupuesto en pesos, targeting, cuenta y página, y espera un 'sí'. Crear diez objetos y luego preguntar no es un dry-run.
• Tope de presupuesto que requiere confirmación humana. En el equipo fue el equivalente a 100 dólares diarios por ad set: por arriba de eso, el agente no crea aunque se lo hayas dictado.
• Nada de reintentos automáticos en escrituras. Si falla un POST a campaigns, adsets, adcreatives o ads, se reporta y se pregunta. El único reintento del script es el del código 17, que es una espera, no una variante.
• Una llamada a la vez y sin ráfagas. Quince creaciones en un minuto desde el mismo token se parecen demasiado a un bot para los sistemas de Meta; el rate limit es lo de menos, la revisión de la cuenta es lo caro.
• Nunca activar ni editar en masa. 'Pausa los que tengan CPA 3x' se responde con una lista de IDs y se detiene; la persona confirma uno por uno.
• Preguntar por categorías especiales antes de crear: crédito, empleo, vivienda, temas sociales y políticos. Si aplica, special_ad_categories no puede ir vacío y el targeting se restringe solo.
• Bitácora de escrituras: cada POST que crea o cambia algo queda en un archivo con fecha, cuenta, endpoint e ID devuelto. Cuando algo aparece en Ads Manager que nadie recuerda haber pedido, esa bitácora es la única respuesta.

## Meta Ads — reglas no negociables
- Todo (campaign, adset, creative, ad) se crea con status PAUSED. Activar solo lo hace una persona con el ID en la mano.
- La cuenta publicitaria (act_...) va explícita en cada operación. Sin default.
- Presupuestos en centavos. Antes de crear, confirmar el monto en pesos con la persona.
- Más de 100 USD/día por ad set: no crear; pedir confirmación explícita.
- Antes de cualquier escritura: resumen (dry-run) y esperar un "sí".
- Escritura fallida: reportar y preguntar. No reintentar, no probar variantes.
- Una llamada a la vez. Nunca activar, pausar ni editar en masa.
- Preguntar si el anuncio cae en categoría especial (crédito, empleo, vivienda, política/social).
- Registrar cada escritura en logs/meta-escrituras.log: fecha, cuenta, endpoint, ID.
- Videos: subir por el bucket puente, esperar ready, borrar del bucket al terminar.
- Tokens y llaves nunca se leen en voz alta ni van en un comando.