# Un video verticale, quaranta account: come un agente pubblica Reel e Short con Shager

_2026-09-15 · Un manuale pratico per agenti che distribuiscono video brevi: controlli sul formato, metadati, testi per account, invio scaglionato e vere chiamate MCP._

Un agente può distribuire un video verticale breve su decine di account Instagram, Facebook e YouTube caricandolo una sola volta con dimensioni e durata, creando un unico post che imposta il formato per ogni social e scrivendo un testo diverso per ogni account. Shager verifica il file rispetto alle regole di ogni social prima di inviare qualsiasi cosa, poi procede account per account con una pausa casuale tra l'uno e l'altro. Il vero lavoro dell'agente sono i metadati, non il caricamento.

Quest'ultima frase è tutta la lezione. Le campagne di video brevi raramente falliscono per colpa del video in sé. Falliscono perché l'agente non sa che la clip dura 3 minuti e 4 secondi, o perché quaranta account ricevono lo stesso identico testo, parola per parola.

## Cosa deve sapere l'agente sul file prima di caricarlo?

Tre numeri: larghezza, altezza e durata. I social classificano e accettano i video brevi in base a questi valori, e un agente che tira a indovinare produce post che finiscono nel formato sbagliato o vengono rifiutati.

La regola di YouTube è la più semplice da enunciare. Secondo la pagina di assistenza di Google sugli [Short di YouTube da tre minuti](https://support.google.com/youtube/answer/15424877?hl=en), i video caricati dal 15 ottobre 2024 con proporzioni quadrate o verticali e una durata fino a tre minuti vengono classificati come Short. Una clip di 3:04 in 9:16 è quindi un video normale, non uno Short, qualunque fosse l'intenzione dell'agente.

Instagram è più permissivo sulle proporzioni, ma ha le sue preferenze. La [documentazione sulla pubblicazione dei contenuti](https://developers.facebook.com/docs/instagram-platform/content-publishing) di Meta per la Instagram Platform elenca i contenitori e i codec accettati per i Reel e consiglia il 9:16 per evitare ritagli o spazi vuoti. Al momento della pubblicazione il video deve trovarsi a un URL raggiungibile pubblicamente, perché è Meta a scaricarlo.

Ecco perché in Shager `upload_media_from_url` accetta i campi facoltativi `width`, `height` e `duration_ms`. Se li passi, la verifica per Reel, Short e storie avviene al caricamento e di nuovo prima della programmazione, invece di presentarsi come un post fallito sull'account numero 23.

Se l'agente non ha questi numeri, deve ricavarli prima del caricamento. In Claude Code o in Codex basta una chiamata a `ffprobe`:

```bash
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height:format=duration \
  -of json launch-teaser.mp4
```

## La sequenza di chiamate MCP

Ecco la sequenza che un agente esegue per un cliente con 38 account collegati, usando il server MCP di Shager su `https://app.shager.ai/api/mcp`. I nomi degli strumenti sono quelli reali; gli ID sono segnaposto.

1. `whoami` per verificare a quale organizzazione appartiene la chiave e se può pubblicare.
2. `list_workspaces` per trovare il workspace del cliente.
3. `list_channels` su quel workspace, per vedere social, stato e formati supportati.
4. `list_groups` per trovare il gruppo che contiene gli account di questa campagna.
5. `upload_media_from_url` con dimensioni e durata.
6. `create_post` come bozza, con i testi per ogni account e il formato per ogni social.
7. `request_approval` se il cliente approva i video, altrimenti `schedule_post`.
8. `get_post` dopo l'orario programmato, per controllare lo stato di ogni account.

La chiamata di caricamento:

```json
{
  "tool": "upload_media_from_url",
  "arguments": {
    "workspace_id": "ws_example",
    "url": "https://cdn.example-agency.com/clients/aurora/launch-teaser.mp4",
    "file_name": "launch-teaser.mp4",
    "width": 1080,
    "height": 1920,
    "duration_ms": 42000
  }
}
```

La bozza del post. Nota che `format` è impostato per ogni canale, perché lo stesso file è un `REEL` su Instagram e Facebook e uno `SHORT` su YouTube:

```json
{
  "tool": "create_post",
  "arguments": {
    "workspace_id": "ws_example",
    "caption": "Aurora opens its new showroom on Thursday. 42 seconds inside.",
    "media_ids": ["med_teaser"],
    "youtube_title": "Inside the new Aurora showroom",
    "youtube_privacy": "public",
    "cta_url": "https://aurora-example.com/showroom",
    "campaign": "showroom-launch",
    "label": "Showroom teaser, week 38",
    "per_channel": [
      { "channel_id": "ch_ig_downtown", "format": "REEL",
        "caption": "Downtown team here. Thursday we open the doors, and this is what you'll see first." },
      { "channel_id": "ch_fb_northside", "format": "REEL",
        "caption": "Northside customers asked for a showroom. Here's a 42 second look before Thursday." },
      { "channel_id": "ch_yt_main", "format": "SHORT",
        "caption": "A first look at the new Aurora showroom, opening Thursday." }
    ],
    "stagger_seconds": [45, 120]
  }
}
```

In un'esecuzione reale `per_channel` ha una voce per ogni account, non tre. Le scrive l'agente; non dovrebbe farlo una persona.

## Perché ogni account ha bisogno del suo testo?

Perché quaranta pagine che pubblicano lo stesso testo nel giro di un'ora sono esattamente lo schema che i sistemi antispam sono costruiti per riconoscere, e perché fa una pessima impressione a chiunque segua due di quelle pagine. Lo stesso [auth.md](/auth.md) di Shager dice esplicitamente agli agenti di variare i testi per ogni account tramite `per_channel`.

Una buona variazione non è un gioco di sinonimi. L'agente dovrebbe ancorare ogni testo a qualcosa di vero su quell'account: la zona, il team, il pubblico. Spieghiamo il metodo nel dettaglio in [variare i testi per account con l'IA](/en/blog/caption-variation-per-account-with-ai), compreso come mantenere stabile il tono del marchio mentre le parole cambiano.

Per i video brevi in particolare, tieni i testi corti. Il messaggio lo porta il video. Un testo che ripete la voce fuori campo spreca spazio.

## Dove va il link in un video breve?

È la parte su cui gli agenti sbagliano più spesso, perché applicano una sola regola a tutti i social.

Su YouTube, Google dichiara nel suo centro assistenza che [gli URL nei commenti e nelle descrizioni degli Short non sono cliccabili](https://support.google.com/youtube/answer/13748639), per ridurre lo spam. Un link per i contatti nel primo commento di uno Short è testo, non un link. Anche su Instagram gli URL nei testi e nei commenti non diventano link. È nei post delle pagine Facebook che un link nel primo commento si comporta come le persone si aspettano.

Quindi, in una campagna di video brevi, l'agente dovrebbe impostare `first_comment` per canale solo dove serve e lasciarlo vuoto sugli Short. Shager genera comunque da `cta_url` un link breve tracciato per ogni account, così i dati sui clic restano per account ovunque il link compaia. Il manuale completo è in [link per i contatti nel primo commento con gli agenti](/en/blog/first-comment-lead-links-with-agents).

## Il ritmo: cosa fa davvero stagger_seconds

`stagger_seconds` è una pausa casuale, in secondi, tra gli account dello stesso social. Il valore predefinito è `[30, 90]`. Con 38 account divisi su tre social, ogni social ha la sua coda, quindi gli account Instagram sono distanziati tra loro e i canali YouTube tra loro.

Per i video di solito lo allargo. Un'esecuzione su 38 account con `[45, 120]` richiede più tempo per finire, ma i post si distribuiscono su un arco che sembra quello di persone che pubblicano, non di uno script. Se al cliente importa che tutto sia online entro una certa ora, l'agente dovrebbe programmare prima invece di stringere lo scaglionamento. Approfondiamo i tempi in [strategia di programmazione per gli agenti](/en/blog/scheduling-strategy-for-agents).

## Controllare il risultato

Dopo l'orario programmato, l'agente chiama `get_post`. La risposta riporta lo stato complessivo del post e quello di ogni account: orario di pubblicazione, URL del post online o l'errore. Tra gli stati del post ci sono `PUBLISHED`, `PARTIALLY_PUBLISHED` e `FAILED`, insieme ad altri elencati nel [documento OpenAPI](https://app.shager.ai/api/v1/openapi.json).

Un risultato `PARTIALLY_PUBLISHED` è normale su larga scala. Il token di un account è scaduto; una pagina ha perso un permesso. Il compito dell'agente è segnalare quegli account per nome alla persona, non ritentare alla cieca. Spesso la soluzione è un nuovo link di collegamento per quell'unico account.

## Una versione REST per gli script

Se la pipeline gira da uno script invece che da un agente in chat, gli stessi due passaggi via REST sono così:

```bash
curl -s https://app.shager.ai/api/v1/workspaces/ws_example/media \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example-agency.com/clients/aurora/launch-teaser.mp4",
       "file_name":"launch-teaser.mp4","width":1080,"height":1920,"duration_ms":42000}'

curl -s https://app.shager.ai/api/v1/workspaces/ws_example/posts \
  -H "Authorization: Bearer $SHAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @teaser-post.json
```

Le risposte arrivano come `{ "data": ... }`, gli errori come `{ "error": { "code", "message" } }`. Il limite è di 120 richieste al minuto per chiave, un valore che una singola campagna video non sfiora nemmeno.

## Domande frequenti

### L'agente può pubblicare un video orizzontale come Short?

No. YouTube classifica gli Short in base a proporzioni e durata, quindi un video orizzontale viene pubblicato come video normale, qualunque `format` tu richieda. Chiedi al montatore un taglio verticale, oppure pubblica la versione orizzontale con `format` impostato su `VIDEO` su YouTube e tieni i Reel per quella verticale.

### Lo stesso video dovrebbe andare su tutti gli account nello stesso giorno?

Si può fare, con testi variati e uno scaglionamento ampio. Con gruppi grandi, molte agenzie dividono l'esecuzione su due o tre giorni, così il pubblico di ogni account non vede la stessa clip condivisa da una pagina vicina alla stessa ora. L'agente può farlo creando post separati per ogni gruppo con valori di `schedule_at` diversi.

### Cosa succede se un account rifiuta il video?

Shager controlla ogni account rispetto alle regole del suo social prima dell'invio, quindi la maggior parte dei problemi emerge già in fase di programmazione, con un motivo chiaro. Se qualcosa fallisce comunque al momento della pubblicazione, `get_post` mostra quale account ha fallito e perché, e il resto dell'esecuzione non ne risente.

## Da dove continuare

Se il tuo agente non è ancora collegato, parti dal [punto di ingresso per gli agenti](/en/agents), che copre il server MCP, l'API REST e la registrazione autonoma. Poi prova un video breve su un gruppo piccolo prima di puntarlo sull'intero elenco del cliente.

---
Source: https://shager.ai/it/blog/agent-short-video-distribution