Integrazione AI Rendervid - Genera Video con Claude Code, Cursor & MCP

Introduzione: Generazione Video Alimentata dall’AI

Creare video in modo programmatico ha tradizionalmente richiesto una conoscenza approfondita di codec video, framework di animazione e pipeline di rendering. Rendervid elimina questa complessità accettando template JSON e producendo video finiti. Quando combini questo con agenti AI che comprendono il linguaggio naturale, ottieni qualcosa di potente: la capacità di descrivere un video in inglese semplice e ricevere un MP4 renderizzato in cambio.

Rendervid colma il divario tra i modelli linguistici AI e la produzione video. Invece di scrivere codice, progettare keyframe o imparare un editor video, dici a un agente AI cosa vuoi. L’agente genera un template JSON valido, lo valida e renderizza l’output finale attraverso il motore di Rendervid. L’intero processo avviene in una singola conversazione.

Questa integrazione è costruita sul Model Context Protocol (MCP), uno standard aperto che permette agli strumenti AI di interagire con servizi esterni attraverso un’interfaccia strutturata. Il server MCP di Rendervid espone 11 strumenti che coprono rendering, validazione, scoperta di template e documentazione, fornendo agli agenti AI tutto ciò di cui hanno bisogno per produrre autonomamente contenuti video professionali.

Cos’è il Model Context Protocol (MCP)?

Il Model Context Protocol è uno standard aperto sviluppato per dare agli assistenti AI accesso strutturato a strumenti esterni e fonti di dati. Piuttosto che affidarsi ai modelli AI per indovinare i formati API o generare codice che chiama endpoint REST, MCP fornisce un’interfaccia tipizzata e scopribile che gli agenti AI possono interrogare in runtime.

Per la generazione video, MCP risolve un problema critico: gli agenti AI devono sapere cosa è possibile prima di poter generare output validi. Senza MCP, un modello AI dovrebbe essere addestrato sul formato specifico dei template di Rendervid, conoscere ogni preset di animazione disponibile e comprendere i vincoli di ogni tipo di layer. Con MCP, l’agente chiama semplicemente get_capabilities e riceve una descrizione completa del sistema, inclusi gli schemi JSON per ogni componente.

Perché MCP è Importante per la Generazione Video AI

• Scoperta in Runtime: Gli agenti AI apprendono cosa può fare Rendervid nel momento in cui si connettono, non al momento dell’addestramento. Questo significa che le nuove funzionalità sono immediatamente disponibili senza riaddestramento.
• Sicurezza dei Tipi: Ogni strumento ha uno schema di input e output definito. L’agente AI sa esattamente quali parametri sono richiesti e di che tipo devono essere.
• Validazione Prima del Rendering: Invece di inviare un template sperando che funzioni, l’agente può validare prima il template e correggere eventuali problemi prima di dedicare tempo al rendering.
• Componibilità degli Strumenti: Gli agenti AI possono concatenare gli strumenti insieme, chiamando list_examples per trovare un template di partenza, modificandolo, chiamando validate_template per verificarlo e poi chiamando render_video per produrre l’output. Tutto in un singolo turno di conversazione.

Riferimento Strumenti Server MCP

Il server MCP di Rendervid espone 11 strumenti organizzati in tre categorie: Rendering, Validazione e Scoperta e Documentazione. Ogni strumento è progettato per dare agli agenti AI la massima autonomia nella generazione di contenuti video.

Strumenti di Rendering

Questi strumenti gestiscono la produzione effettiva di output video e immagini dai template JSON.

render_video

Genera un file video completo da un template JSON. Questo è lo strumento di rendering principale per produrre output MP4, WebM o MOV.

Parametri:

• template (oggetto, richiesto) – Il template JSON completo che definisce scene, layer, animazioni e impostazioni di output.
• inputs (oggetto, opzionale) – Coppie chiave-valore per la sostituzione delle variabili del template.
• output_format (stringa, opzionale) – Formato di output: mp4, webm o mov. Predefinito: mp4.

Esempio di utilizzo da parte di un agente AI:

{
  "tool": "render_video",
  "arguments": {
    "template": {
      "outputSettings": {
        "width": 1080,
        "height": 1920,
        "fps": 30,
        "duration": 10
      },
      "scenes": [
        {
          "duration": 10,
          "layers": [
            {
              "type": "text",
              "text": "Saldi Estivi - 50% di Sconto",
              "fontSize": 72,
              "fontFamily": "Montserrat",
              "color": "#FFFFFF",
              "position": { "x": 540, "y": 960 },
              "animations": [
                {
                  "type": "fadeInUp",
                  "duration": 0.8,
                  "delay": 0.2
                }
              ]
            }
          ]
        }
      ]
    },
    "output_format": "mp4"
  }
}

Restituisce: Un URL o percorso del file al file video renderizzato.

render_image

Genera un singolo fotogramma o immagine statica da un template JSON. Utile per creare miniature, grafiche per social media, fotogrammi poster e materiali di marketing statici.

Parametri:

• template (oggetto, richiesto) – Il template JSON che definisce la composizione dell’immagine.
• inputs (oggetto, opzionale) – Valori di sostituzione delle variabili del template.
• output_format (stringa, opzionale) – Formato di output: png, jpeg o webp. Predefinito: png.
• frame (numero, opzionale) – Quale fotogramma renderizzare (per estrarre un momento specifico da un template animato).

Quando usare render_image vs render_video:

• Usa render_image per output statico: miniature, banner, post sui social media, diapositive di presentazione.
• Usa render_video per qualsiasi cosa con movimento: animazioni, transizioni, audio, clip video.

start_render_async

Avvia un lavoro di rendering asincrono per video di lunga durata (tipicamente oltre 30 secondi). Invece di attendere il completamento del rendering in modo sincrono, questo strumento restituisce un ID lavoro che puoi interrogare con check_render_status.

Parametri:

• template (oggetto, richiesto) – Il template JSON completo.
• inputs (oggetto, opzionale) – Valori delle variabili del template.
• output_format (stringa, opzionale) – Formato di output desiderato.

Restituisce: Una stringa job_id che può essere utilizzata con check_render_status e list_render_jobs.

Quando usare il rendering asincrono:

• Video più lunghi di 30 secondi
• Template con molte scene o animazioni complesse
• Flussi di lavoro di rendering batch dove vuoi inviare più lavori e raccogliere i risultati successivamente
• Ambienti di rendering cloud dove le richieste sincrone di lunga durata potrebbero scadere

check_render_status

Controlla lo stato corrente di un lavoro di rendering asincrono avviato con start_render_async.

Parametri:

• job_id (stringa, richiesto) – L’ID lavoro restituito da start_render_async.

Restituisce: Un oggetto contenente:

• status – Uno tra queued, rendering, completed o failed.
• progress – Una percentuale (0-100) che indica il progresso del rendering.
• output_url – L’URL del video finito (presente solo quando status è completed).
• error – Messaggio di errore se il lavoro è fallito.

Esempio di flusso di polling:

Agente AI:
1. start_render_async → job_id: "abc-123"
2. check_render_status("abc-123") → status: "rendering", progress: 35
3. check_render_status("abc-123") → status: "rendering", progress: 78
4. check_render_status("abc-123") → status: "completed", output_url: "https://..."

list_render_jobs

Elenca tutti i lavori di rendering asincroni, sia attivi che completati. Utile per monitorare operazioni di rendering batch o rivedere output recenti.

Parametri:

• status_filter (stringa, opzionale) – Filtra per stato: queued, rendering, completed, failed o all. Predefinito: all.
• limit (numero, opzionale) – Numero massimo di lavori da restituire.

Restituisce: Un array di oggetti lavoro, ciascuno con job_id, status, progress, created_at e output_url (se completato).

Strumenti di Validazione e Scoperta

Questi strumenti aiutano gli agenti AI a comprendere cosa può fare Rendervid e a verificare che i template siano corretti prima del rendering.

validate_template

Valida un template JSON prima del rendering. Questo strumento controlla la struttura del template, i tipi di campo, i vincoli dei valori e verifica persino che gli URL dei media (immagini, video, file audio) siano accessibili. Eseguire la validazione prima del rendering previene tempo sprecato su template che fallirebbero durante il processo di rendering.

Parametri:

• template (oggetto, richiesto) – Il template JSON da validare.
• check_urls (booleano, opzionale) – Se verificare che gli URL dei media siano accessibili. Predefinito: true.

Restituisce: Un oggetto contenente:

• valid – Booleano che indica se il template è valido.
• errors – Array di oggetti errore con path, message e severity per ogni problema trovato.
• warnings – Array di oggetti avviso per problemi non critici (es. variabili non utilizzate, dimensioni molto grandi).

Cosa cattura la validazione:

• Campi richiesti mancanti (es. una scena senza duration)
• Tipi di campo non validi (es. una stringa dove è previsto un numero)
• Tipi di layer o preset di animazione sconosciuti
• URL di media rotti o inaccessibili (immagini, video, file audio)
• Valori fuori intervallo (es. dimensioni negative, fps sopra il massimo)
• Errori di sintassi delle variabili del template

Esempio di risposta di validazione:

{
  "valid": false,
  "errors": [
    {
      "path": "scenes[0].layers[2].src",
      "message": "URL ha restituito HTTP 404: https://example.com/missing-image.png",
      "severity": "error"
    },
    {
      "path": "scenes[1].duration",
      "message": "La durata della scena deve essere un numero positivo",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "path": "outputSettings.width",
      "message": "Larghezza 7680 è molto grande e potrebbe risultare in rendering lento",
      "severity": "warning"
    }
  ]
}

get_capabilities

Restituisce una descrizione completa di tutto ciò che Rendervid può fare. Questo è tipicamente il primo strumento che un agente AI chiama quando inizia un’attività di generazione video. La risposta include i tipi di layer disponibili, i preset di animazione, le funzioni di easing, i filtri, i formati di output e i loro schemi JSON.

Parametri: Nessuno.

Restituisce: Un oggetto strutturato contenente:

• layerTypes – Tutti i tipi di layer disponibili (text, image, video, shape, audio, group, lottie, custom) con i loro schemi JSON e proprietà configurabili.
• animations – Tutti i preset di animazione raggruppati per categoria (entrance, exit, emphasis, keyframe) con descrizioni e parametri configurabili.
• easingFunctions – Tutte le oltre 30 funzioni di easing con descrizioni ed esempi di utilizzo.
• filters – Filtri visivi disponibili (blur, brightness, contrast, saturate, grayscale, sepia, ecc.) con intervalli di parametri.
• outputFormats – Formati di output supportati per rendering video e immagini con i loro vincoli.
• inputTypes – Tipi di variabili del template e regole di validazione.
• sceneTransitions – Tutti i 17 tipi di transizione scena con i loro parametri.

Perché questo strumento è critico per gli agenti AI:

La risposta delle capacità è un’API auto-descrittiva. Un agente AI non ha bisogno di essere pre-addestrato sul formato del template di Rendervid. Può chiamare get_capabilities in runtime, ricevere lo schema completo e generare template validi al primo tentativo. Quando Rendervid aggiunge nuove funzionalità, animazioni o tipi di layer, gli agenti AI ottengono automaticamente accesso ad esse attraverso questo strumento senza alcuna modifica al codice.

get_example

Carica un template di esempio specifico per nome. Gli agenti AI usano questo per recuperare un template funzionante come punto di partenza, quindi lo modificano per soddisfare i requisiti dell’utente.

Parametri:

• name (stringa, richiesto) – Il nome del template di esempio (es. instagram-story, product-showcase, animated-bar-chart).

Restituisce: Il template JSON completo per l’esempio richiesto, pronto per essere renderizzato o modificato.

Esempio:

L'agente AI chiama: get_example("instagram-story")
Restituisce: Template completo di storia Instagram 1080x1920 con layer di testo,
         immagine di sfondo e animazioni di entrata

list_examples

Sfoglia il catalogo completo di oltre 50 template di esempio organizzati per categoria. Gli agenti AI usano questo per trovare template di partenza rilevanti per la richiesta dell’utente.

Parametri:

• category (stringa, opzionale) – Filtra per categoria (es. social-media, marketing, data-visualization, typography, e-commerce).

Restituisce: Un array di oggetti metadati di esempio, ciascuno con:

• name – Identificatore del template da usare con get_example.
• category – Categoria del template.
• description – Cosa crea il template.
• dimensions – Larghezza e altezza di output.
• duration – Durata del template in secondi.

Strumenti di Documentazione

Questi strumenti forniscono documentazione di riferimento dettagliata che gli agenti AI possono consultare durante la costruzione dei template.

get_component_docs

Restituisce documentazione dettagliata per un componente o tipo di layer specifico. Include descrizioni delle proprietà, campi richiesti vs opzionali, valori predefiniti ed esempi di utilizzo.

Parametri:

• component (stringa, richiesto) – Il nome del componente/tipo di layer (es. text, image, video, shape, audio, group, lottie, custom, AnimatedLineChart, TypewriterEffect).

Restituisce: Documentazione completa inclusi:

• Tabella delle proprietà con tipi, predefiniti e descrizioni
• Schema JSON per il componente
• Esempi di utilizzo
• Note sulle differenze di rendering browser vs Node.js

get_animation_docs

Restituisce il riferimento completo degli effetti di animazione, inclusi tutti i preset di animazione entrance, exit, emphasis e keyframe.

Parametri:

• animation (stringa, opzionale) – Nome specifico dell’animazione per ottenere documentazione dettagliata (es. fadeInUp, bounceIn, slideOutLeft). Se omesso, restituisce il catalogo completo delle animazioni.

Restituisce: Documentazione dell’animazione inclusi:

• Nome dell’animazione e categoria (entrance, exit, emphasis, keyframe)
• Descrizione dell’effetto visivo
• Parametri configurabili (duration, delay, easing)
• Valori predefiniti
• Casi d’uso consigliati

get_component_defaults

Restituisce i valori predefiniti e lo schema JSON completo per un tipo di componente specifico. Gli agenti AI usano questo per capire come appare un componente valido minimale e quali proprietà possono sovrascrivere.

Parametri:

• component (stringa, richiesto) – Il nome del componente/tipo di layer.

Restituisce: Un oggetto JSON con:

• defaults – Valori predefiniti completi per ogni proprietà
• schema – Schema JSON che definisce la struttura, i tipi e i vincoli del componente
• required – Elenco delle proprietà richieste

Esempio di risposta per un layer di testo:

{
  "defaults": {
    "type": "text",
    "text": "",
    "fontSize": 24,
    "fontFamily": "Arial",
    "color": "#000000",
    "fontWeight": "normal",
    "textAlign": "center",
    "position": { "x": 0, "y": 0 },
    "opacity": 1,
    "rotation": 0,
    "animations": []
  },
  "required": ["type", "text"],
  "schema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Il contenuto testuale da visualizzare" },
      "fontSize": { "type": "number", "minimum": 1, "maximum": 500 },
      "fontFamily": { "type": "string", "description": "Nome Google Font o font di sistema" },
      "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
    }
  }
}

get_easing_docs

Restituisce il riferimento completo per tutte le funzioni di easing disponibili. Le funzioni di easing controllano la curva di accelerazione delle animazioni, determinando se iniziano lentamente, finiscono lentamente, rimbalzano o seguono una curva elastica.

Parametri:

• easing (stringa, opzionale) – Nome specifico della funzione di easing per documentazione dettagliata. Se omesso, restituisce l’elenco completo.

Restituisce: Documentazione per ogni funzione di easing inclusi:

• Nome della funzione (es. easeInOutCubic, easeOutBounce, spring)
• Descrizione matematica della curva
• Descrizione visiva della sensazione del movimento
• Casi d’uso consigliati
• Equivalente CSS (dove applicabile)

Configurazione dell’Integrazione AI

Connettere Rendervid al tuo strumento AI richiede l’aggiunta del server MCP alla configurazione del tuo strumento. Il processo di configurazione varia leggermente tra gli strumenti, ma il concetto di base è lo stesso: punta il tuo strumento AI al punto di ingresso del server MCP di Rendervid.

Prerequisiti

Prima di configurare qualsiasi strumento AI, assicurati di avere:

1. Node.js 18+ installato sul tuo sistema
2. Rendervid clonato e compilato dal repository GitHub :

git clone https://github.com/AceDZN/rendervid.git
cd rendervid
npm install
cd mcp
npm install
npm run build

3. FFmpeg installato (richiesto per l’output video):

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (con Chocolatey)
choco install ffmpeg

Claude Desktop / Claude Code

Aggiungi il server MCP di Rendervid al file di configurazione di Claude Desktop.

Posizione del file di configurazione:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configurazione:

{
  "mcpServers": {
    "rendervid": {
      "command": "node",
      "args": ["/percorso/a/rendervid/mcp/build/index.js"],
      "env": {}
    }
  }
}

Sostituisci /percorso/a/rendervid con il percorso effettivo della tua installazione Rendervid.

Per Claude Code (CLI), aggiungi la stessa configurazione al file .claude/mcp.json del tuo progetto o alle impostazioni globali di Claude Code. Claude Code rileverà automaticamente il server MCP ed esporrà tutti gli 11 strumenti durante le tue sessioni di codifica.

Dopo aver salvato la configurazione, riavvia Claude Desktop o Claude Code. Puoi verificare la connessione chiedendo a Claude: “Quali strumenti Rendervid sono disponibili?” Claude dovrebbe elencare tutti gli 11 strumenti MCP.

Cursor IDE

Aggiungi il server MCP di Rendervid alla configurazione MCP di Cursor.

File di configurazione: .cursor/mcp.json nella radice del tuo progetto (o impostazioni globali di Cursor).

{
  "mcpServers": {
    "rendervid": {
      "command": "node",
      "args": ["/percorso/a/rendervid/mcp/build/index.js"]
    }
  }
}

Dopo il salvataggio, riavvia Cursor. Gli strumenti Rendervid saranno disponibili nell’assistente AI di Cursor, permettendoti di generare video direttamente dal tuo editor.

Windsurf IDE

Windsurf supporta i server MCP attraverso la sua configurazione AI. Aggiungi il server Rendervid alle impostazioni MCP di Windsurf:

{
  "mcpServers": {
    "rendervid": {
      "command": "node",
      "args": ["/percorso/a/rendervid/mcp/build/index.js"]
    }
  }
}

Consulta la documentazione di Windsurf per la posizione esatta del file di configurazione, poiché può variare in base alla versione e al sistema operativo.

Configurazione MCP Generica

Qualsiasi strumento che implementa la specifica client MCP può connettersi al server MCP di Rendervid. Il server comunica tramite stdio (standard input/output), che è il trasporto MCP predefinito.

Per integrarsi con un client MCP personalizzato:

1. Avvia il processo del server MCP:

   node /percorso/a/rendervid/mcp/build/index.js
   

2. Comunica tramite stdin/stdout utilizzando il protocollo JSON-RPC di MCP.
3. Chiama tools/list per scoprire gli strumenti disponibili.
4. Chiama tools/call con il nome dello strumento e gli argomenti per eseguire qualsiasi strumento.

Il server MCP è stateless. Ogni chiamata allo strumento è indipendente e il server può gestire richieste concorrenti da più client.

Flusso di Lavoro AI: Esempi End-to-End

I seguenti esempi mostrano come gli agenti AI utilizzano gli strumenti MCP di Rendervid per passare da un prompt in linguaggio naturale a un video finito.

Esempio 1: Creazione di Contenuti per Social Media

Prompt utente: “Crea una storia Instagram di 10 secondi che promuove i saldi estivi con testo animato e uno sfondo sfumato”

Flusso di lavoro dell’agente AI:

Passo 1 – Scopri le capacità:

L’agente chiama get_capabilities per apprendere i tipi di layer disponibili, i preset di animazione e i vincoli di output. Scopre che i layer text e shape sono disponibili, esistono le animazioni fadeInUp e scaleIn, e le storie Instagram usano la risoluzione 1080x1920.

Passo 2 – Trova un template di partenza:

L’agente chiama list_examples con category: "social-media" e trova un template instagram-story. Quindi chiama get_example("instagram-story") per caricare il JSON completo del template.

Passo 3 – Costruisci il template:

Usando l’esempio come riferimento, l’agente costruisce un template personalizzato:

{
  "outputSettings": {
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "duration": 10
  },
  "scenes": [
    {
      "duration": 10,
      "layers": [
        {
          "type": "shape",
          "shapeType": "rectangle",
          "width": 1080,
          "height": 1920,
          "gradient": {
            "type": "linear",
            "angle": 135,
            "stops": [
              { "color": "#FF6B35", "position": 0 },
              { "color": "#F72585", "position": 0.5 },
              { "color": "#7209B7", "position": 1 }
            ]
          }
        },
        {
          "type": "text",
          "text": "SALDI ESTIVI",
          "fontSize": 96,
          "fontFamily": "Montserrat",
          "fontWeight": "bold",
          "color": "#FFFFFF",
          "position": { "x": 540, "y": 700 },
          "animations": [
            { "type": "fadeInUp", "duration": 0.8, "delay": 0.3 }
          ]
        },
        {
          "type": "text",
          "text": "50% DI SCONTO SU TUTTO",
          "fontSize": 64,
          "fontFamily": "Montserrat",
          "color": "#FFE066",
          "position": { "x": 540, "y": 850 },
          "animations": [
            { "type": "fadeInUp", "duration": 0.8, "delay": 0.6 }
          ]
        },
        {
          "type": "text",
          "text": "Acquista Ora  →",
          "fontSize": 48,
          "fontFamily": "Montserrat",
          "color": "#FFFFFF",
          "position": { "x": 540, "y": 1200 },
          "animations": [
            { "type": "scaleIn", "duration": 0.6, "delay": 1.2 }
          ]
        }
      ]
    }
  ]
}

Passo 4 – Valida:

L’agente chiama validate_template con il JSON del template. La risposta torna come valid: true senza errori.

Passo 5 – Renderizza:

L’agente chiama render_video con il template validato e riceve un URL al file MP4 finito.

Esempio 2: Automazione Video di Marketing

Prompt utente: “Genera un video vetrina prodotto per le nostre nuove cuffie. Usa questa immagine del prodotto: https://example.com/headphones.png . Il nome del prodotto è ‘SoundPro X1’ e il prezzo è €299.”

Flusso di lavoro dell’agente AI:

1. get_capabilities – Apprende sui layer immagine, stili di testo e opzioni di animazione.
2. list_examples – Trova un template product-showcase nella categoria e-commerce.
3. get_example("product-showcase") – Carica il template completo di vetrina prodotto, che usa variabili del template per nome prodotto, immagine e prezzo.
4. Modifica il template – Aggiorna gli inputs con i dati del prodotto dell’utente:

   {
     "inputs": {
       "productName": "SoundPro X1",
       "productImage": "https://example.com/headphones.png",
       "price": "€299",
       "tagline": "Suono Premium, Ridefinito"
     }
   }
   

5. validate_template – Verifica il template e conferma che https://example.com/headphones.png sia accessibile.
6. render_video – Produce il video finale di vetrina prodotto.

Questo flusso di lavoro dimostra come gli agenti AI sfruttano le variabili del template per creare contenuti personalizzati da template riutilizzabili. Lo stesso template di vetrina prodotto può generare centinaia di video unici scambiando gli input.

Esempio 3: Generazione di Visualizzazione Dati

Prompt utente: “Crea un grafico a barre animato che mostra i ricavi trimestrali: Q1: €1,2M, Q2: €1,8M, Q3: €2,1M, Q4: €2,7M”

Flusso di lavoro dell’agente AI:

1. get_capabilities – Scopre il tipo di layer custom e il componente integrato AnimatedLineChart.
2. get_component_docs("AnimatedLineChart") – Legge la documentazione per il componente grafico, apprendendo sul formato dati, configurazione colori, etichette assi e opzioni di animazione.
3. get_component_defaults("AnimatedLineChart") – Ottiene i valori predefiniti e lo schema JSON per comprendere la configurazione minima richiesta.
4. Costruisce un template con un layer componente personalizzato:

   {
     "type": "custom",
     "component": "AnimatedLineChart",
     "props": {
       "data": [
         { "label": "Q1", "value": 1200000 },
         { "label": "Q2", "value": 1800000 },
         { "label": "Q3", "value": 2100000 },
         { "label": "Q4", "value": 2700000 }
       ],
       "colors": ["#4361EE", "#3A0CA3", "#7209B7", "#F72585"],
       "title": "Ricavi Trimestrali 2025",
       "yAxisLabel": "Ricavi (EUR)",
       "animationDuration": 2
     }
   }
   

5. validate_template – Conferma che la struttura del template sia corretta.
6. render_video – Genera il video del grafico animato.

API Auto-Descrittiva: Come le Capacità Rendono Efficaci gli Agenti AI

Lo strumento get_capabilities è la pietra angolare dell’integrazione AI di Rendervid. Implementa un pattern di API auto-descrittiva, dove il sistema dice agli agenti AI esattamente cosa può fare, quali parametri sono richiesti e quali valori sono validi. Questo elimina la necessità per i modelli AI di memorizzare o essere addestrati sull’API specifica di Rendervid.

Cosa Contiene la Risposta delle Capacità

Quando un agente AI chiama get_capabilities, riceve una risposta strutturata che copre ogni aspetto del sistema di rendering:

Tipi di Layer con Schemi JSON:

{
  "layerTypes": {
    "text": {
      "description": "Renderizza testo con controllo completo dello stile",
      "schema": {
        "properties": {
          "text": { "type": "string", "required": true },
          "fontSize": { "type": "number", "default": 24, "min": 1, "max": 500 },
          "fontFamily": { "type": "string", "default": "Arial" },
          "color": { "type": "string", "format": "hex-color" },
          "position": { "type": "object", "properties": { "x": {}, "y": {} } },
          "animations": { "type": "array", "items": { "$ref": "#/animations" } }
        }
      }
    },
    "image": { "..." : "..." },
    "video": { "..." : "..." },
    "shape": { "..." : "..." },
    "audio": { "..." : "..." },
    "group": { "..." : "..." },
    "lottie": { "..." : "..." },
    "custom": { "..." : "..." }
  }
}

Preset di Animazione:

La risposta delle capacità elenca ogni preset di animazione con la sua categoria, parametri configurabili e descrizione. Un agente AI che riceve questi dati sa che fadeInUp è un’animazione di entrata con parametri duration, delay ed easing, e che muove l’elemento verso l’alto mentre lo sfuma.

Funzioni di Easing:

Tutte le oltre 30 funzioni di easing sono elencate con descrizioni, così l’agente AI può selezionare la curva giusta per ogni animazione. Per esempio, easeOutBounce è descritto come simulazione di un effetto rimbalzo alla fine dell’animazione, che l’agente può raccomandare per contenuti giocosi o che attirano l’attenzione.

Filtri ed Effetti:

Filtri visivi come blur, brightness, contrast, saturate, grayscale e sepia sono documentati con i loro intervalli di parametri, permettendo all’agente AI di applicare effetti di post-elaborazione a qualsiasi layer.

Perché le API Auto-Descrittive Sono Importanti

Le API tradizionali richiedono documentazione che i modelli AI potrebbero o meno aver visto durante l’addestramento. Un’API auto-descrittiva fornisce documentazione in runtime, assicurando che l’agente AI abbia sempre informazioni correnti e accurate. Quando Rendervid aggiunge un nuovo preset di animazione o tipo di layer, ogni agente AI connesso lo vede immediatamente attraverso get_capabilities. Nessun aggiornamento della documentazione, nessun riaddestramento, nessuna discrepanza di versione.

Best Practice per la Generazione Video AI

Segui queste linee guida per ottenere i migliori risultati quando usi agenti AI per generare video Rendervid.

1. Valida Sempre Prima del Rendering

Chiama validate_template prima di ogni rendering. Il rendering è computazionalmente costoso, e la validazione è quasi istantanea. Lo strumento di validazione cattura problemi che causerebbero il fallimento di un rendering o produrrebbero output inaspettato:

• URL di media rotti (immagini, video, file audio che restituiscono 404)
• Struttura JSON non valida o campi richiesti mancanti
• Valori fuori intervallo per dimensioni, dimensioni font o durate
• Preset di animazione o tipi di layer sconosciuti

Un tipico flusso di lavoro AI dovrebbe sempre includere la validazione come passo prima di chiamare render_video o render_image.

2. Parti dagli Esempi

Invece di costruire template da zero, gli agenti AI dovrebbero usare list_examples e get_example per trovare un template di partenza rilevante. I template di esempio sono testati e noti per produrre buon output. Partire da un esempio e modificarlo è più veloce e meno soggetto a errori che generare una struttura di template completamente nuova.

Approccio consigliato:

1. Chiama list_examples con una categoria rilevante
2. Chiama get_example per il template più corrispondente
3. Modifica il template per soddisfare i requisiti specifici dell’utente
4. Valida e renderizza

3. Usa Prompt Descrittivi

Quando richiedi video da un agente AI, sii specifico su:

• Dimensioni e piattaforma – “storia Instagram 1080x1920” è meglio di “un video verticale”
• Durata – “intro di 10 secondi” è meglio di “un video breve”
• Stile e atmosfera – “sfondo scuro con testo neon e animazioni rimbalzanti” dà all’agente AI una direzione chiara
• Struttura del contenuto – “Tre righe di testo che appaiono una dopo l’altra con animazioni fade-in” è più attuabile di “del testo animato”

4. Itera sui Template

La generazione video è iterativa. Dopo il primo rendering, rivedi l’output e chiedi all’agente AI di regolare elementi specifici:

• “Rendi il testo del titolo più grande e cambia il colore in oro”
• “Rallenta le animazioni di entrata e aggiungi un ritardo di 0,5 secondi tra ogni riga”
• “Aggiungi un filtro blur sottile all’immagine di sfondo”
• “Cambia l’easing da lineare a easeOutCubic per un movimento più fluido”

L’agente AI può modificare il template esistente e ri-renderizzare senza ricominciare, rendendo l’iterazione veloce ed efficiente.

5. Sfrutta le Variabili del Template per la Produzione Batch

Se hai bisogno di più variazioni dello stesso video (prodotti diversi, lingue diverse, dati diversi), chiedi all’agente AI di creare un template con variabili . Questo ti permette di renderizzare molti video da un singolo template passando inputs diversi:

{
  "inputs": {
    "productName": "Scarpe da Corsa Pro",
    "productImage": "https://example.com/shoes.png",
    "price": "€149",
    "tagline": "Corri Più Veloce, Vai Più Lontano"
  }
}

6. Usa il Rendering Asincrono per Video Lunghi

Per video più lunghi di 30 secondi o template con animazioni complesse, usa start_render_async invece di render_video. Questo previene timeout e permette all’agente AI di eseguire altri compiti mentre il video viene renderizzato in background.

Scoperta dei Template: Navigazione di Oltre 100 Esempi

Rendervid include oltre 100 template di esempio che coprono 32 categorie, fornendo agli agenti AI una ricca libreria di punti di partenza per qualsiasi compito di generazione video.

Come gli Agenti AI Scoprono i Template

Il flusso di lavoro di scoperta dei template usa due strumenti in sequenza:

1. list_examples – Sfoglia il catalogo con filtraggio opzionale per categoria per trovare template rilevanti.
2. get_example – Carica il template JSON completo per un esempio specifico.

Categorie di Template

Gli agenti AI possono filtrare gli esempi per categoria per trovare rapidamente punti di partenza rilevanti:

Scoperta dei Template in Pratica

Quando un utente chiede “un grafico animato che mostra dati di vendita”, l’agente AI:

1. Chiama list_examples(category: "data-visualization") e riceve un elenco di template relativi ai grafici.
2. Identifica animated-bar-chart come la migliore corrispondenza basata sulla descrizione.
3. Chiama get_example("animated-bar-chart") per caricare il template completo.
4. Esamina la struttura del template per capire come sono formattati i dati.
5. Sostituisce i dati di esempio con le cifre di vendita effettive dell’utente.
6. Valida e renderizza.

Questo approccio discovery-first significa che gli agenti AI producono costantemente template ben strutturati perché stanno costruendo su esempi testati piuttosto che generare JSON di template da zero.

Esplorazione di Tutti i Template Disponibili

Per vedere ogni template disponibile, un agente AI può chiamare list_examples senza filtro di categoria. La risposta include metadati per tutti gli oltre 100 template, permettendo all’agente di cercare tra le categorie per la migliore corrispondenza. Ogni voce include il nome del template, categoria, descrizione, dimensioni e durata, dando all’agente informazioni sufficienti per fare una selezione informata.

Strumenti AI Supportati

Il server MCP di Rendervid funziona con qualsiasi strumento che implementa la specifica client del Model Context Protocol. I seguenti strumenti sono stati testati e confermati funzionare con Rendervid:

Poiché MCP è uno standard aperto, qualsiasi futuro strumento che aggiunge supporto client MCP sarà automaticamente compatibile con il server MCP di Rendervid. Non sono richieste modifiche al server o ai suoi strumenti.

Prossimi Passi

• Panoramica Rendervid – Scopri tutte le funzionalità di Rendervid, formati di output e architettura.
• Sistema Template – Approfondimento sulla struttura del template JSON, variabili e sistema di input.
• Riferimento Componenti – Documentazione per tutti i tipi di layer e componenti React personalizzati.
• Guida al Deployment – Distribuisci Rendervid su AWS Lambda, Azure Functions, Google Cloud Run o Docker per rendering su scala cloud.
• Repository GitHub – Codice sorgente, tracker problemi e contributi della community.