Utiliser un agent

Une fois connecté, demandez simplement à votre agent en langage naturel. Par exemple : « Liste les présets d'image de SimpliGen, puis génère un renard roux dans la neige et montre-moi le fichier. »

Ce qu'un agent peut faire

• Voir ce qui est disponible: tous les présets avec lesquels il peut générer, image ou vidéo, et si les modèles sont installés localement.
• Générer: lancer un travail d'image ou de vidéo à partir d'une invite, avec des images de référence ou une image de démarrage optionnelles. Il peut s'exécuter localement, sur SimpliGen Cloud, ou choisir automatiquement.
• Suivre les travaux: vérifier le statut et attendre un résultat.
• Retourner les résultats: renvoyer le chemin du fichier terminé, ou afficher l'image directement dans le chat.
• Préparer les présets: commencer à télécharger les modèles d'un préset local pour qu'il devienne prêt à l'emploi.
• Exécuter les studios: lister les recettes installées dans UGC Studio et Product Studio, remplir leurs entrées (un personnage, un produit, quelques choix) et les exécuter, exactement comme un clic sur Générer le ferait. Voir UGC Studio et Product Studio ci-dessous.

Local vs cloud

Les générations s'exécutent localement par défaut et ne coûtent jamais de crédits. Cloud n'est proposé que lorsque vous avez SimpliGen Cloud connecté, et un agent bien comporté demande avant de dépenser des crédits (ou suit le mode d'approbation automatique dans lequel vous l'exécutez).

Maintenir un agent dans les limites

• Plafond de dépenses. Lorsque vous connectez un agent, vous pouvez définir un plafond de dépenses cloud optionnel. L'agent ne peut jamais dépenser plus que cela sur les crédits cloud, peu importe ce qu'on lui demande. La génération locale est toujours autorisée et ne compte jamais contre ce plafond. Laissez le plafond vide pour aucune limite, ou réglez-le sur 0 pour bloquer complètement cloud (local uniquement).
• Les tokens sont locaux et révocables. Un token d'appairage ne fonctionne que par rapport à SimpliGen sur votre propre machine, et vous pouvez le révoquer à tout moment depuis Agents connectés. La révocation est instantanée.
• L'application reste en contrôle. L'agent communique avec SimpliGen; il ne peut pas accéder directement à votre compte cloud ou à votre clé.

Si votre agent s'exécute sur une machine différente, voir Accès distant.

UGC Studio et Product Studio

Les deux studios sont des collections de recettes: pipelines multi-étapes (une édition, une surélévation, une vidéo) avec un petit formulaire en façade. Un agent peut exécuter les mêmes recettes via run_recipe.

1. Trouver une recette. list_recipes retourne tout ce qui est installé sur cet appareil, avec une category (ugc ou product) et les inputs que chaque recette demande: la clé, son type, si elle est requise, et les options autorisées pour les choix.
2. Apporter les sujets. Une entrée subject prend un id de personnage (de list_characters) ou un id de produit. Pour ajouter un produit, téléchargez sa photo avec upload_file et appelez create_product avec un nom et une courte description; la description est tissée dans les invites de la recette.
3. L'exécuter. run_recipe avec l'id de la recette et les entrées remplies. Elle retourne un id d'exécution immédiatement. engine est local par défaut quand chaque preset de l'étape est installé, ou cloud quand connecté; get_recipe montre la préparation par étape pour que l'agent puisse dire à l'avance.
4. Attendre. wait_for_recipe_run bloque jusqu'à ce que l'exécution se termine et retourne le résultat de chaque étape plus le fichier final. cancel_recipe_run arrête une exécution tôt.

Une exécution lancée par un agent atterrit dans la Galerie groupée comme une exécution de studio et apparaît dans l'historique d'exécution de la recette, afin que vous puissiez la rouvrir, la réutiliser ou la refaire dans l'application par la suite. Les exécutions cloud sont facturées avant leur démarrage et comptent contre le plafond de dépenses de l'agent.

Character Studio

Un agent peut créer des personnages réutilisables et générer des images de scènes ou des vidéos animées à partir d'eux. Avant de commencer, appelez get_status et vérifiez characters.enabled: c'est true quand le moteur fonctionne et que les présets de personnages requis sont installés. characters.basegenPresets et characters.editPresets rapportent combien de présets de chaque type sont prêts.

Chemin de création 1: décrire

L'agent appelle list_character_features pour obtenir les caractéristiques d'identité disponibles (teinte de peau, couleur de cheveux, forme des yeux, etc.), choisit des valeurs pour chacune, puis appelle create_character avec mode: 'generate' et une carte identity de { featureId: optionId }. L'outil interroge en interne jusqu'à ce que le portrait de base soit prêt, puis retourne l'objet caractère prêt (avec characterId et base_image_url). L'agent n'a pas besoin d'interroger un id de travail; le personnage est prêt à être utilisé dès que l'outil retourne. Chaque caractéristique et option est indexée par son id (utilisez ceci dans les appels API); le label sur chaque option est une description en anglais clair pour que l'agent puisse présenter les choix à l'utilisateur de manière lisible.

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

Chemin de création 2: télécharger en tant que base

Si l'utilisateur a une image qu'il souhaite utiliser directement, l'agent appelle create_character avec mode: 'upload' et le chemin local absolu de l'image dans baseFilePath. L'outil gère le téléchargement en interne. Aucune étape de génération ne s'exécute; le personnage est prêt immédiatement.

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

Chemin de création 3: vision-recréer

L'agent (avec vision) examine une photo utilisateur, lit les caractéristiques visibles de la personne, les mappe aux options retournées par list_character_features, puis suit le chemin 1 (décrire). La photo n'est pas utilisée comme image de base. Un portrait frais est généré pour recréer l'apparence à partir des caractéristiques décrites. Ceci est utile quand l'utilisateur veut une version stylisée de lui-même ou d'une autre personne plutôt qu'une ressemblance photographique.

Exemple de flux de raisonnement d'agent:

1. L'utilisateur partage une photo.
2. L'agent appelle list_character_features et examine les ids d'option.
3. L'agent inspecte la photo et remplit une carte identity: { skinTone: "light", hairColor: "red", hair: "longWaves" }.
4. L'agent appelle create_character avec mode: 'generate' et l'identity remplie.
5. L'outil retourne l'objet caractère prêt (pas d'interrogation nécessaire; il attend en interne). L'agent affiche le portrait de base à l'utilisateur.

Générer des scènes et des vidéos

Une fois qu'un personnage est prêt (base acceptée), passez son characterId à generate_character_image ou 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"
})

Les deux retournent des ids de travail. Utilisez wait_for_result pour interroger, puis get_result_image (images) ou le chemin du fichier de get_job (vidéos) pour récupérer la sortie.

Remarque: La génération de personnages est local uniquement en v1. Le moteur doit fonctionner (characters.enabled: true dans get_status) et les présets de personnages requis doivent être installés. La dispatch cloud n'est pas supportée pour les outils de personnage.

Changer les présets par appel

Appelez list_character_presets pour voir quels présets sont installés et leurs ids. Chaque appel à generate_character_image et generate_character_video accepte un remplacement de préset optionnel:

• generate_character_image accepte presetId, un id de préset d'édition d'identité de la liste identityEdit.
• generate_character_video accepte framePresetId (préset d'édition d'identité pour l'étape de cadre) et videoPresetId (préset i2v pour l'étape d'animation).

Si vous omettez le remplacement, la valeur par défaut collante du personnage est utilisée (ou la valeur par défaut du système si aucune n'est définie).

Définir une valeur par défaut collante par personnage

Utilisez set_character_preset pour enregistrer un préset par défaut sur un personnage afin que vous n'ayez pas besoin de passer presetId à chaque appel:

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

Passez null pour l'un ou l'autre champ pour effacer cette valeur par défaut:

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

Améliorer une image ou une vidéo

enhance_character_media exécute un préset de surélévation sur n'importe quel bien de personnage. Avant de l'appeler, vérifiez characters.enhancePresets dans get_status (ou inspectez les tableaux enhanceImage/enhanceVideo de list_character_presets) pour confirmer qu'un préset de surélévation est installé. Chaque préset d'amélioration liste ses facteurs d'échelle disponibles dans supportedScales.

Options source:

• Un travail terminé: passez l'id du travail dans jobId. Le type de média est déduit du travail.
• Un fichier téléchargé: téléchargez d'abord avec upload_file, puis passez le handle dans filePath. Incluez mediaType: "image" ou mediaType: "video".
• Le portrait de base du personnage: passez target: "base". Ceci traite toujours la source comme une image.

Paramètres supplémentaires:

• scale: facteur de surélévation (par exemple 2 ou 4; doit être dans les supportedScales du préset).
• keepResolution: si true, le résultat est surélevé puis redimensionné aux dimensions source d'origine, produisant une image plus nette de la même taille sans changer le nombre de pixels de sortie.
• applyAsBase: si true, le résultat surélevé remplace automatiquement le portrait de base du personnage une fois le travail complété.

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
})

Flux d'examen de cadre: générer -> améliorer -> animer

Vous pouvez examiner et améliorer un cadre fixe avant de vous engager dans le rendu vidéo:

1. Appelez generate_character_frame pour produire un seul cadre fixe. Ceci retourne { jobIds: [...] }; utilisez jobIds[0] comme id de travail de cadre.
2. Interrogez jobIds[0] avec wait_for_result et examinez l'image avec get_result_image.
3. Optionnellement appelez enhance_character_media avec jobId: jobIds[0] pour surélever le cadre. Ceci retourne un nouvel id de travail; interrogez-le jusqu'à son achèvement.
4. Appelez animate_character avec jobId défini sur l'id de travail d'amélioration complété (ou jobIds[0] du cadre si vous avez ignoré l'amélioration). animate_character accepte tout travail d'image complété comme sa source.

// 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"
})

Régénérer une base sur place

Utilisez regenerate_character_base pour mettre en file d'attente une nouvelle génération de portrait de base pour un personnage existant sans créer un nouveau dossier de personnage. Vous pouvez optionnellement basculer vers un préset de base différent ou mettre à jour les caractéristiques d'identité en même temps:

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

L'outil interroge en interne, accepte automatiquement le nouveau portrait une fois le travail complété, et retourne l'objet caractère prêt. L'agent n'a pas besoin d'interroger un id de travail par la suite.