Utilizzo di un agente

View as Markdown Open in ChatGPT Open in Claude

Una volta connesso, basta chiedere al tuo agente in linguaggio naturale. Ad esempio: "Elenca i preset per immagini di SimpliGen, quindi genera una volpe rossa nella neve e mostrami il file."

Cosa può fare un agente

Vedere cosa è disponibile: ogni preset con cui può generare, immagine o video, e se i modelli sono installati localmente.
Generare: avviare un lavoro di immagine o video da un prompt, con immagini di riferimento opzionali o un'immagine iniziale. Può funzionare localmente, su SimpliGen Cloud, oppure scegliere automaticamente.
Tracciare i lavori: controllare lo stato e attendere un risultato.
Restituire i risultati: restituire il percorso del file completato, oppure mostrare l'immagine direttamente nella chat.
Preparare i preset: iniziare a scaricare i modelli di un preset locale in modo che sia pronto per l'uso.
Eseguire gli studi: elencare le ricette installate in UGC Studio e Product Studio, compilare i loro input (un personaggio, un prodotto, alcune scelte) ed eseguirli, esattamente come un clic su Genera. Vedi UGC Studio e Product Studio di seguito.

Le generazioni vengono eseguite localmente per impostazione predefinita e non costano crediti. Il cloud viene offerto solo quando hai SimpliGen Cloud connesso, e un agente ben comportato chiede prima di spendere crediti (o segue la modalità di approvazione automatica in cui lo esegui).

Mantenere un agente entro i limiti

Limite di spesa. Quando connetti un agente puoi impostare un limite di spesa cloud opzionale. L'agente non può mai spendere più di quello in crediti cloud, indipendentemente da cosa gli viene chiesto di fare. La generazione locale è sempre consentita e non conta mai contro di essa. Lascia il limite vuoto per nessun limite, oppure impostalo su 0 per bloccare completamente il cloud (solo locale).
I token sono locali e revocabili. Un token di accoppiamento funziona solo su SimpliGen sulla tua macchina, e puoi revocarlo in qualsiasi momento da Agenti connessi. La revoca è istantanea.
L'app rimane sotto controllo. L'agente comunica con SimpliGen; non può accedere direttamente al tuo account cloud o alla tua chiave.

Prova prima con qualcosa di piccolo

Prima di affidare a un agente un grande batch, prova un paio di singole generazioni locali in modo che tu possa vedere come formula le richieste e cosa restituisce.

Se il tuo agente gira su una macchina diversa, vedi Accesso remoto.

UGC Studio e Product Studio

Entrambi gli studi sono raccolte di ricette: pipeline multi-step (una modifica, un upscale, un video) con un piccolo modulo sulla parte anteriore. Un agente può eseguire le stesse ricette tramite run_recipe.

Trova una ricetta. list_recipes restituisce tutto ciò che è installato su questo dispositivo, con una category (ugc o product) e gli inputs che ogni ricetta richiede: la chiave, il suo tipo, se è obbligatorio e le opzioni consentite per le scelte.
Porta i soggetti. Un input subject accetta un character id (da list_characters) o un product id. Per aggiungere un prodotto, carica la sua foto con upload_file e chiama create_product con un nome e una breve descrizione; la descrizione è intrecciata nei prompt della ricetta.
Eseguila. run_recipe con l'id della ricetta e gli input compilati. Restituisce un run id immediatamente. engine è local per impostazione predefinita quando ogni preset dello step è installato, oppure cloud quando connesso; get_recipe mostra la disponibilità per step in modo che l'agente possa anticipare.
Attendi. wait_for_recipe_run si blocca fino al completamento dell'esecuzione e restituisce il risultato di ogni step più il file finale. cancel_recipe_run interrompe un'esecuzione in anticipo.

Un'esecuzione avviata da un agente finisce nella Galleria raggruppata come un'esecuzione di studio e appare nella cronologia di esecuzione della ricetta, quindi puoi riaprirla, riusarla o ripeterla nell'app in seguito. Le esecuzioni cloud hanno un prezzo prima di iniziare e contano verso il limite di spesa dell'agente.

Character Studio

Un agente può creare personaggi riutilizzabili e generare scene o video animati da essi. Prima di iniziare, chiama get_status e controlla characters.enabled: è true quando il motore è in esecuzione e i preset di personaggio richiesti sono installati. characters.basegenPresets e characters.editPresets riportano quanti preset di ogni tipo sono pronti.

Percorso di creazione 1: descrivi

L'agente chiama list_character_features per ottenere le caratteristiche di identità disponibili (tono della pelle, colore dei capelli, forma degli occhi, e così via), sceglie i valori per ciascuno, quindi chiama create_character con mode: 'generate' e una mappa identity di { featureId: optionId }. Lo strumento esegue il polling internamente fino a quando il ritratto di base non è pronto, quindi restituisce l'oggetto carattere pronto (con characterId e base_image_url). L'agente non ha bisogno di eseguire il polling di un id di lavoro; il personaggio è pronto all'uso non appena lo strumento restituisce. Ogni caratteristica e opzione è identificata dal suo id (usalo nelle chiamate API); l'label su ogni opzione è una descrizione in inglese semplice in modo che l'agente possa presentare le scelte all'utente in modo leggibile.

create_character({
  name: "Mara",
  gender: "woman",
  mode: "generate",
  identity: { skinTone: "tan", hairColor: "black", eyeShape: "almond" }
})

Percorso di creazione 2: carica come base

Se l'utente ha un'immagine che vuole usare direttamente, l'agente chiama create_character con mode: 'upload' e il percorso locale assoluto dell'immagine in baseFilePath. Lo strumento gestisce il caricamento internamente. Nessun step di generazione viene eseguito; il personaggio è pronto immediatamente.

create_character({
  name: "Mara",
  gender: "woman",
  mode: "upload",
  baseFilePath: "/absolute/path/to/photo.jpg"
})

Percorso di creazione 3: vision-ricrea

L'agente (con visione) guarda una foto dell'utente, legge le caratteristiche visibili della persona, le mappa alle opzioni restituite da list_character_features, e quindi segue il percorso 1 (descrivi). La foto non viene utilizzata come immagine di base. Un nuovo ritratto viene generato per ricreeare l'aspetto dalle caratteristiche descritte. Questo è utile quando l'utente vuole una versione stilizzata di se stesso o di qualcun altro piuttosto che una somiglianza fotografica.

Esempio del flusso di ragionamento dell'agente:

L'utente condivide una foto.
L'agente chiama list_character_features e rivede gli option ids.
L'agente ispeziona la foto e compila una mappa identity: { skinTone: "light", hairColor: "red", hair: "longWaves" }.
L'agente chiama create_character con mode: 'generate' e l'identity compilata.
Lo strumento restituisce l'oggetto personaggio pronto (nessun polling necessario; attende internamente). L'agente mostra il ritratto di base all'utente.

Generazione di scene e video

Una volta che un personaggio è pronto (base accettata), passa il suo characterId a generate_character_image o generate_character_video:

generate_character_image({
  characterId: "char-abc123",
  prompt: "standing on a beach at golden hour",
  aspect: "16:9"
})

generate_character_video({
  characterId: "char-abc123",
  prompt: "standing in a park",
  motion: "waving at the camera"
})

Entrambi restituiscono job ids. Usa wait_for_result per il polling, quindi get_result_image (immagini) o il percorso del file da get_job (video) per recuperare l'output.

Nota: La generazione di caratteri è solo locale nella v1. Il motore deve essere in esecuzione (characters.enabled: true in get_status) e i preset di carattere richiesti devono essere installati. La dispatch al cloud non è supportata per gli strumenti dei caratteri.

Cambio di preset per chiamata

Chiama list_character_presets per vedere quali preset sono installati e i loro ids. Ogni chiamata a generate_character_image e generate_character_video accetta un override di preset opzionale:

generate_character_image accetta presetId, un identity-edit preset id dalla lista identityEdit.
generate_character_video accetta framePresetId (identity-edit preset per lo step di frame) e videoPresetId (i2v preset per lo step di animazione).

Se ometti l'override, viene utilizzato il default appiccicaticcio del personaggio (o il default del sistema se nessuno è impostato).

Impostazione di un default appiccicaticcio per personaggio

Usa set_character_preset per registrare un preset di default su un personaggio in modo che non sia necessario passare presetId ad ogni chiamata:

set_character_preset({
  characterId: "char-abc123",
  imagePresetId: "flux-character-edit",
  videoPresetId: "ltx-i2v-standard"
})

Passa null per uno qualsiasi dei campi per cancellare quel default:

set_character_preset({
  characterId: "char-abc123",
  imagePresetId: null
})

Miglioramento di un'immagine o video

enhance_character_media esegue un upscale preset su qualsiasi asset di personaggio. Prima di chiamarla, controlla characters.enhancePresets in get_status (o ispeziona gli array enhanceImage/enhanceVideo da list_character_presets) per confermare che un preset di upscale è installato. Ogni preset di miglioramento elenca i suoi fattori di scala disponibili in supportedScales.

Opzioni di origine:

Un lavoro completato: passa l'id del lavoro in jobId. Il tipo di media è dedotto dal lavoro.
Un file caricato: carica con upload_file per primo, quindi passa l'handle in filePath. Includi mediaType: "image" o mediaType: "video".
Il ritratto di base del personaggio: passa target: "base". Questo tratta sempre l'origine come un'immagine.

Parametri aggiuntivi:

scale: fattore di upscale (es. 2 o 4; deve essere nei supportedScales del preset).
keepResolution: se true, il risultato viene upscalato e poi ridimensionato alle dimensioni dell'origine originale, producendo un'immagine più nitida della stessa dimensione senza cambiare il numero di pixel dell'output.
applyAsBase: se true, il risultato upscalato sostituisce automaticamente il ritratto di base del personaggio una volta che il lavoro si completa.

enhance_character_media({
  characterId: "char-abc123",
  jobId: "gen-xyz",
  scale: 2
})

enhance_character_media({
  characterId: "char-abc123",
  target: "base",
  scale: 4,
  keepResolution: true,
  applyAsBase: true
})

Flusso di revisione dei frame: genera -> migliora -> anima

Puoi rivedere e migliorare un fotogramma statico prima di impegnarti nel rendering video:

Chiama generate_character_frame per produrre un singolo fotogramma statico. Questo restituisce { jobIds: [...] }; usa jobIds[0] come id del frame job.
Esegui il polling di jobIds[0] con wait_for_result e rivedi l'immagine con get_result_image.
Opzionalmente chiama enhance_character_media con jobId: jobIds[0] per upscalare il fotogramma. Questo restituisce un nuovo id di lavoro; esegui il polling fino al completamento.
Chiama animate_character con jobId impostato all'id del lavoro di miglioramento completato (o jobIds[0] dal frame se hai saltato il miglioramento). animate_character accetta qualsiasi job di immagine completato come sua origine.

// Step 1: generate frame
generate_character_frame({
  characterId: "char-abc123",
  prompt: "walking through a city street"
})
// -> { jobIds: ["gen-frame-111"] }

// Step 3: upscale the frame
enhance_character_media({
  characterId: "char-abc123",
  jobId: "gen-frame-111",
  scale: 2
})
// -> { jobId: "gen-enhance-222" }

// Step 4: animate from the upscaled frame
animate_character({
  characterId: "char-abc123",
  jobId: "gen-enhance-222",
  motion: "walking confidently"
})

Rigenerazione di una base in posizione

Usa regenerate_character_base per mettere in coda una nuova generazione di ritratto di base per un personaggio esistente senza creare un nuovo record di personaggio. Puoi opzionalmente passare a un preset di base diverso o aggiornare le caratteristiche di identità allo stesso tempo:

regenerate_character_base({
  characterId: "char-abc123",
  basePresetId: "flux-character-base-v2",
  identity: { skinTone: "light", hairColor: "blonde", hair: "bob" }
})

Lo strumento esegue il polling internamente, accetta automaticamente il nuovo ritratto una volta che il lavoro si completa, e restituisce l'oggetto personaggio pronto. L'agente non ha bisogno di eseguire il polling di un id di lavoro in seguito.