AI Agents
Riferimento degli strumenti MCP
Gli strumenti che il server MCP di SimpliGen espone agli agenti IA e l'API di controllo locale sottostante.
SimpliGen integra un server MCP (@simpligen/mcp) che connette un agente IA all'app SimpliGen in esecuzione su una connessione locale autenticata con token. L'agente chiama gli strumenti MCP; il server li inoltro all'API di controllo locale dell'app. Vedi Connetti un agente per configurarlo.
Strumenti
| Strumento | Cosa fa |
|---|---|
list_capabilities | Elenca ogni preset con cui l'agente può generare (immagine o video), i suoi input e opzioni, se è pronto localmente, l'idoneità al cloud e il costo in crediti. |
get_status | Segnala lo stato del motore, la connessione al cloud, il saldo dei crediti, il progetto attivo e il blocco della capacità characters (flag abilitato, conteggi dei preset installati per base/edit/i2v e enhancePresets, il numero di preset di upscale installati). |
start_engine | Avvia il motore locale se non è già in esecuzione. Restituisce lo stato del motore; quando un avvio a freddo supera la durata della chiamata, engineStarting è true e get_status segnala quando è operativo. Non fa nulla se il motore è già in esecuzione e non installa mai uno mancante (connector 0.3.0 o più recente). |
stop_engine | Arresta il motore locale e libera la sua VRAM. La generazione cloud non ne risente (connector 0.3.0 o più recente). |
restart_engine | Riavvia il motore locale, dopo aver installato o rimosso un nodo personalizzato, o quando si blocca (connector 0.3.0 o più recente). |
list_projects | Elenca i progetti (i contenitori che contengono le generazioni). |
create_project | Crea un nuovo progetto. |
upload_file | Carica un'immagine o video locale e ottieni un handle da passare a generate. |
list_loras | Elenca i LoRA utente installati (nome, modello base, parole trigger) in modo da poterli passare a generate. |
generate | Avvia una generazione di immagine o video. Scegli local, cloud o auto. Facoltativamente passa loras: [{ name, weight }] (backend locale, preset dove inputs.supportsLoras è true; usa list_loras per i nomi) e un negativePrompt (termini aggiuntivi, aggiunti dopo il negativo predefinito del preset; nelle esecuzioni cloud il preset predefinito viene usato così com'è). options accetta i campi nominati (steps, cfg, seed, resolution, aspectRatio, durationSeconds) e qualsiasi Controllo Avanzato che il preset dichiara sotto list_capabilities → options.controls, come unlock, shift o high_steps, come chiave di primo livello (connector 0.2.0 o più recente). Restituisce un id di lavoro. |
get_prompt_guide | Leggi la guida ai prompt per un preset (presetId) prima di scriverne il prompt: come il modello legge un prompt, struttura, lunghezza, wording di telecamera e movimento, negativi, wording dei personaggi ed esempi. La risposta contiene family, generic (true quando non esiste una guida specifica del modello) e il testo della guida text. Connector 0.6.0 o più recente; generate dice agli agenti di chiamarlo prima. |
get_job | Ottieni lo stato e il risultato di un lavoro, incluso il percorso di output una volta terminato. |
wait_for_result | Attendi fino a quando un lavoro non termina, fallisce o scade. |
list_jobs | Elenca i lavori di generazione recenti. |
cancel_job | Annulla un lavoro in coda o in esecuzione. |
prepare_preset | Avvia il download dei modelli di un preset locale in modo che diventi pronto per l'esecuzione. |
get_result_image | Restituisci l'immagine di un lavoro terminato inline per la visualizzazione. I risultati video restituiscono un percorso di file. |
list_recipe_blocks | Elenca i blocchi costitutivi per l'authoring di una ricetta: punti di ingresso (crea immagine o video, modifica immagine, upscale) e ogni preset utilizzabile come passaggio, ciascuno con il suo contratto di porta (input di cui ha bisogno, cosa produce, quali punti di ingresso si adatta). |
compose_recipe | Crea una nuova ricetta da una specifica di alto livello (passaggi ordinati fissati ai preset, più eventuali input) e salvala come bozza. SimpliGen cablaggio automatico delle porte, la catena dei media step-to-step e un input di prompt per passaggio, quindi convalida. Restituisce l'id della ricetta più la convalida. |
validate_recipe | Esecuzione a secco di una specifica di ricetta (o una configurazione grezza) senza salvare e ottieni errori precisi da correggere prima di comporre. |
list_recipes | Elenca le bozze di ricette salvate su questo dispositivo. |
get_recipe | Ottieni una ricetta salvata e la sua configurazione completa per id. |
publish_recipe | Invia una ricetta salvata al Creator Marketplace (in coda per revisione umana). Necessita un account connesso; pubblica gratuitamente a meno che non sia impostato un prezzo di token una tantum. |
run_recipe | Esegui una ricetta installata (quelle in UGC Studio e Product Studio, o una bozza) con i suoi input compilati. Un input soggetto accetta un id di personaggio o prodotto, gli input media accettano handle di upload, gli input di testo e scelta accettano valori semplici. Stessa pipeline che fare clic su Generate nello studio. Restituisce un id di esecuzione. |
get_recipe_run | Stato di un'esecuzione di ricetta: stato complessivo, ogni passaggio con il suo stato e risultato, e il percorso del risultato finale una volta terminato. |
wait_for_recipe_run | Blocca fino al completamento di un'esecuzione di ricetta (o al passaggio di un timeout) e restituisci l'esecuzione finale. |
list_recipe_runs | Esecuzioni recenti di una ricetta con il loro stato e risultati. |
cancel_recipe_run | Interrompi un'esecuzione di ricetta. Nessun ulteriore passaggio inizia; un passaggio locale in volo viene interrotto. |
list_subjects | Ogni soggetto che un input soggetto di ricetta può assumere: personaggi e prodotti, con i loro id. |
list_products | I prodotti salvati su questo dispositivo. |
create_product | Salva un prodotto da una foto caricata (nome, descrizione, categoria) in modo che Product Studio e le ricette UGC possano usarlo. Restituisce l'id del prodotto. |
remove_product | Elimina un prodotto e la sua foto. |
list_characters | Elenca tutti i personaggi attivi in Character Studio. |
get_character | Ottieni i dettagli e le immagini di un singolo personaggio per id. |
list_character_features | Elenca tutte le caratteristiche di identità (tonalità della pelle, capelli, ecc.) e le loro opzioni, per l'uso durante la creazione di un personaggio per descrizione. |
list_character_presets | Elenca i preset installati disponibili per ogni ruolo di personaggio: generazione di ritratti base, modifica dell'identità, animazione da immagine a video e miglioramento (upscale). Ogni preset di miglioramento include un array supportedScales. |
create_character | Crea un nuovo personaggio. Supporta tre percorsi: descrivere (genera un ritratto base dalle selezioni di caratteristiche), caricare (usa la tua immagine come base) e vision-ricrea (caratteristiche descritte dall'agente da una foto utente). In modalità di generazione, lo strumento esegue il polling internamente fino a quando il ritratto base non è pronto e restituisce l'oggetto personaggio pronto. In modalità di caricamento, il personaggio è pronto immediatamente. |
generate_character_image | Genera un'immagine di scena per un personaggio esistente per prompt. Accetta un presetId facoltativo per selezionare quale preset di modifica dell'identità usare per questa chiamata. Restituisce uno o più id di lavoro da esaminare tramite wait_for_result. |
generate_character_video | Genera una clip video animata per un personaggio esistente. Accetta framePresetId facoltativo (preset di modifica dell'identità per il passaggio del fotogramma) e videoPresetId (preset i2v per il passaggio di animazione). Restituisce id di lavoro sia per il passaggio del fotogramma che per il passaggio di animazione. |
generate_character_frame | Genera un singolo fotogramma statico per un personaggio senza animarlo. Utile quando vuoi rivedere o migliorare il fotogramma prima di animarlo. Accetta un presetId facoltativo. Restituisce { jobIds: [...] }; usa jobIds[0] come id di lavoro del fotogramma. |
animate_character | Anima un personaggio da un fotogramma completato o da qualsiasi lavoro di immagine completato. Passa jobId (un id di lavoro da qualsiasi generazione completata) o un filePath (percorso assoluto dell'immagine locale). Accetta un videoPresetId facoltativo. Restituisce un id di lavoro video. |
set_character_preset | Imposta un preset predefinito permanente per personaggio per la generazione di immagini (imagePresetId) e/o la generazione di video (videoPresetId). Passa null per cancellare un'impostazione predefinita. Le successive chiamate a generate_character_image e generate_character_video usano questi valori predefiniti a meno che non siano sovrascritti per chiamata. |
enhance_character_media | Upscale o migliora un'immagine o video di personaggio. La fonte può essere un lavoro completato (jobId), un file caricato (handle filePath), o il ritratto base del personaggio (target: 'base'). Accetta scale (fattore di upscale), keepResolution (upscale e quindi ridimensiona indietro alle dimensioni di origine per un risultato di stessa dimensione più nitido) e applyAsBase (sostituisci il ritratto base del personaggio con il risultato upscalato). Restituisce un id di lavoro. |
regenerate_character_base | Rigenera il ritratto base per un personaggio esistente sul posto, facoltativamente passando a un preset base diverso o aggiornando l'identità. Nessun nuovo personaggio viene creato. Esegue il polling internamente, accetta automaticamente la nuova base e restituisce l'oggetto personaggio pronto. L'agente non ha bisogno di esaminare un id di lavoro in seguito. |
remove_character | Elimina definitivamente un personaggio e i dati associati. |
list_films | Elenca i film di Video Studio di un progetto (connector 0.5.0 o più recente, così come tutti gli strumenti di film di seguito). |
create_film | Crea un film vuoto: forma, risoluzione, dove viene renderizzato, preset per ogni tipo di scena. Fornisce la sua timeline. |
get_film | Leggi la timeline di un film: tempo, cast, ogni clip con il suo numero, inizio e lunghezza in secondi e battute, scene e stato di ripresa, le tracce, marcatori e intervallo di esportazione. |
update_film_settings | Cambia la forma del film, la risoluzione, dove viene renderizzato, i preset, Soggetto e stile, e il cast e la posizione che ogni clip eredita. |
add_track | Metti un file audio caricato sulla timeline: canto, musica, dialogo o effetti. |
move_track | Sposta l'audio di una traccia, silenzialo o imposta il suo volume. |
detect_tempo | Imposta il tempo del film e le linee delle battute dalla sua canzone. Successivamente, i tempi possono essere espressi in battute. |
add_clip | Aggiungi una clip vuota in un momento, per una durata. |
update_clip | Scrivi una clip in un passaggio: scene (prompt, lunghezza, linea pronunciata o cantata, chi la dice, inquadratura), cast, posizione, come inizia (fresca o continua dalla clip precedente; none e frame sono anche accettati, come fresca e continua), quali tracce sente, preset. |
move_clip | Sposta una clip a un nuovo inizio o a un'altra corsia video. |
trim_clip | Cambia la lunghezza di una clip o dove inizia dentro la sua ripresa. |
remove_clip | Rimuovi una clip. |
apply_film_plan | Disponi un'intera bozza in un passaggio: clip sulle battute con le loro scene, cast e link. Ogni problema torna tutto in una volta; nulla cambia a meno che tutto non sia valido. |
set_fades | Sfuma una clip o una traccia dentro e fuori. |
add_marker | Metti un marcatore nominato sul righello. |
set_export_range | Esporta solo parte del film, o tutto. |
render_clips | Renderizza le clip che ne hanno bisogno, o quelle nominate. Risponde subito con cosa è iniziato, cosa è trattenuto e il costo del cloud. |
wait_for_renders | Attendi fino a quando nessuna clip non è in fase di rendering e rispondi la timeline. |
list_takes | Elenca le riprese di una clip. |
use_take | Fai in modo che una delle riprese di una clip sia quella che mostra. |
export_film | Unisci il film in un video con la sua musica e fornisci il percorso del file. |
list_locations | Elenca le posizioni della Libreria. |
create_location | Salva una posizione da un'immagine caricata o da un lavoro di immagine terminato. |
Con il film aperto in Video Studio, ogni modifica che un agente fa appare immediatamente e si annulla con Ctrl+Z. Vedi Un agente crea un video musicale per una procedura completa.
Come si connette
L'agente esegue il server MCP con npx -y @simpligen/mcp su stdio. Il server si autentica all'app con un token di accoppiamento (SIMPLIGEN_TOKEN) e trova la porta locale dell'app automaticamente. L'app SimpliGen deve essere in esecuzione. Crea un token in Impostazioni, nella sezione "Connetti un agente".
Stai costruendo un'integrazione personalizzata?
Gli strumenti MCP si inoltrano a un'API di controllo HTTP locale che puoi chiamare direttamente da qualsiasi linguaggio. Vedi il riferimento dell'API di controllo.
Limiti di spesa
Ogni token può portare un limite di spesa. Un limite vuoto significa uso cloud illimitato, 0 significa solo generazione locale e un numero positivo limita la spesa cloud a quel numero di crediti. La generazione locale è sempre consentita e non conta mai rispetto al limite.
Un agente crea un videoclip musicale
Dai a un agente un brano e un cast, e guardalo costruire un videoclip nello Video Studio, clip per clip, in tempo reale.
Riferimento API di controllo
L'API HTTP locale che SimpliGen espone sul tuo computer, per creare integrazioni personalizzate ed eseguire generazioni in modalità headless.