エージェントの使用

SimpliGenでエージェントが実行できることと、その範囲内での管理方法。

View as Markdown Open in ChatGPT Open in Claude

接続後は、エージェントに自然言語で質問してください。例えば、「SimpliGenの画像プリセットをリストアップして、雪の中の赤いキツネを生成し、ファイルを表示してください」などです。

エージェントが実行できること

利用可能な機能を確認: 生成できるすべてのプリセット(画像またはビデオ)と、モデルがローカルにインストールされているかどうか。
生成: プロンプトから画像またはビデオジョブを開始できます。オプションで参照画像またはスタート画像を使用できます。ローカルで実行することも、SimpliGen Cloudで実行することも、自動選択することもできます。
ジョブを追跡: ステータスを確認し、結果を待つ。
結果を返す: 完成したファイルパスを返すか、チャット内で画像を表示する。
プリセットを準備: ローカルプリセットのモデルをダウンロード開始して、使用可能な状態にする。
スタジオを実行: UGC StudioおよびProduct Studioにインストールされているレシピをリストアップし、その入力(キャラクター、プロダクト、複数の選択肢)を記入して実行する。これはGenerate をクリックするのと同じです。以下の UGC StudioおよびProduct Studio を参照してください。

ローカルvs クラウド

生成はデフォルトでローカルで実行され、クレジットはかかりません。クラウドはSimliGen Cloudが接続されている場合にのみ提供され、適切に動作するエージェントはクレジット支出前に確認するか、実行しているオートアプルーブモードに従います。

エージェントを範囲内に保つ

支出上限。 エージェントを接続する際、オプションのクラウド支出上限を設定できます。エージェントが何をするよう求められても、クラウドクレジットでそれ以上に支出することはできません。ローカル生成は常に許可され、支出上限に対してカウントされません。上限を空のままにしてシステムに制限なし、または 0に設定してクラウドを完全にブロック(ローカルのみ)してください。
トークンはローカルで取り消し可能。 ペアリングトークンは自分のマシン上のSimpliGenに対してのみ機能し、いつでも 接続済みエージェント から取り消すことができます。取り消しは即座に適用されます。
アプリが制御を維持。 エージェントはSimliGenと通信し、クラウドアカウントやキーに直接アクセスすることはできません。

まず少数のテストを実行してください

エージェントに大量バッチを処理させる前に、ローカル生成を1、2件実行して、リクエストの表現方法と返される内容を確認してください。

エージェントが別のマシンで実行されている場合、リモートアクセスを参照してください。

UGC StudioおよびProduct Studio

どちらのスタジオもレシピのコレクションです: マルチステップパイプライン(編集、アップスケール、ビデオ)の前に簡単なフォームがあります。エージェントは run_recipe で同じレシピを実行できます。

レシピを探す。 list_recipes はこのデバイスにインストールされているすべてのレシピを返します。各レシピには category (ugc または product)と、各レシピが求める inputs があります。キー、種類、必須かどうか、選択肢の許可されたオプション。
サブジェクトを用意。 subject 入力は、キャラクター ID (list_characters から)またはプロダクト ID を受け入れます。プロダクトを追加するには、 upload_file でその写真をアップロードし、名前と簡単な説明を使用して create_product を呼び出します。説明はレシピのプロンプトに織り込まれます。
実行。 run_recipe にレシピ ID と記入された入力を使用します。実行 ID がすぐに返されます。 engine はすべてのステップのプリセットがインストールされているときはデフォルトで local、接続されているときは cloud です。 get_recipe は各ステップの準備状況を示すため、エージェントは事前に確認できます。
待つ。 wait_for_recipe_run は実行が終了するまでブロックし、各ステップの結果とファイルを返します。 cancel_recipe_run で実行を早期に停止します。

エージェントが開始した実行はギャラリーにスタジオ実行のようにグループ化され、レシピの実行履歴に表示されるため、アプリ内で後から開き直したり、再利用したり、やり直したりできます。クラウド実行は開始前に価格設定され、エージェントの支出上限に対してカウントされます。

エージェントは再利用可能なキャラクターを作成し、そこからシーン画像またはアニメーション動画を生成できます。開始する前に、 get_status を呼び出し、 characters.enabled を確認します。エンジンが実行中で、必要なキャラクタープリセットがインストールされている場合は true です。 characters.basegenPresets と characters.editPresets は、各タイプの準備完了プリセット数をレポートします。

作成パス 1: 説明

エージェントは list_character_features を呼び出して、利用可能なアイデンティティ機能(肌の色、髪の色、目の形など)を取得し、各機能の値を選択してから、 mode: 'generate' と { featureId: optionId } のアイデンティティマップを使用して create_character を呼び出します。ツールは内部的にポーリングしてベースポートレートが準備完了になるまで待機し、準備完了したキャラクターオブジェクト( characterId と base_image_url を含む)を返します。エージェントはジョブ ID をポーリングする必要がなく、キャラクターはツールが返されるとすぐに使用可能になります。各機能とオプションは id でキー付けされます(API呼び出しでこれを使用してください)。各オプションの label は平易な英語の説明であり、エージェントが読みやすい方法でユーザーに選択肢を提示できます。

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

作成パス 2: ベースとしてアップロード

ユーザーが直接使用したい画像を持っている場合、エージェントは mode: 'upload' を使用して create_character を呼び出し、 baseFilePath に画像の絶対ローカルパスを渡します。ツールはアップロードを内部的に処理します。生成ステップは実行されず、キャラクターはすぐに準備完了になります。

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

作成パス 3: ビジョン再作成

ビジョン機能を持つエージェントはユーザーの写真を見て、その人の見える機能を読み、 list_character_features が返すオプションにマップしてから、パス 1(説明)に従います。写真はベース画像として使用されません。説明された機能から見た目を再作成するために新しいポートレートが生成されます。これは、ユーザーが写真的な似顔絵ではなく、自分自身または他の誰かのスタイル化されたバージョンを望んでいる場合に便利です。

エージェント推論フローの例:

ユーザーが写真を共有。
エージェントが list_character_features を呼び出し、オプション ID をレビュー。
エージェントが写真を検査し、アイデンティティマップを記入: { skinTone: "light", hairColor: "red", hair: "longWaves" }。
エージェントが mode: 'generate' と記入されたアイデンティティを使用して create_character を呼び出し。
ツールが準備完了したキャラクターオブジェクトを返す(ポーリングは不要。内部的に待機します)。エージェントがユーザーにベースポートレートを表示。

シーンとビデオの生成

キャラクターが準備完了になったら(ベース承認)、その characterId を generate_character_image または 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"
})

両方ともジョブ ID を返します。 wait_for_result を使用してポーリングし、 get_result_image (画像)または get_job からのファイルパス(ビデオ)を使用して出力を取得します。

注: キャラクター生成は v1 ではローカルのみです。エンジンが実行中( get_status で characters.enabled: true )で、必要なキャラクタープリセットがインストールされている必要があります。キャラクターツールでのクラウドディスパッチはサポートされていません。

呼び出しごとにプリセットを切り替える

list_character_presets を呼び出して、インストールされているプリセットとその ID を確認します。 generate_character_image および generate_character_video への各呼び出しは、オプションのプリセットオーバーライドを受け入れます:

generate_character_image は presetId を受け入れます。これは identityEdit リストからのアイデンティティ編集プリセット ID です。
generate_character_video は framePresetId (フレームステップ用のアイデンティティ編集プリセット)と videoPresetId (アニメーションステップ用の i2v プリセット)を受け入れます。

オーバーライドを省略すると、キャラクターのスティッキーデフォルトが使用されます(設定されていない場合はシステムデフォルト)。

キャラクターごとのスティッキーデフォルトを設定

set_character_preset を使用して、キャラクターのデフォルトプリセットを記録し、すべての呼び出しで presetId を渡す必要がないようにします:

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

いずれかのフィールドに null を渡してそのデフォルトをクリアします:

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

画像またはビデオを拡張

enhance_character_media は、すべてのキャラクターアセットでアップスケールプリセットを実行します。これを呼び出す前に、 get_status で characters.enhancePresets を確認するか(または list_character_presets から enhanceImage/enhanceVideo 配列を検査)、アップスケールプリセットがインストールされていることを確認します。各拡張プリセットは、その supportedScales で利用可能なスケール係数をリストします。

ソースオプション:

完成したジョブ: jobId にジョブ ID を渡します。メディアタイプはジョブから推測されます。
アップロードされたファイル: 先に upload_file を使用してアップロードし、 filePath にハンドルを渡します。 mediaType: "image" または mediaType: "video" を含めます。
キャラクターベースポートレート: target: "base" を渡します。これは常にソースを画像として扱います。

追加パラメータ:

scale: アップスケール係数(例: 2 または 4。プリセットの supportedScales に含まれている必要があります)。
keepResolution: true の場合、結果はアップスケール後に元のソース寸法にリサイズされ、出力ピクセル数を変更せずに、より鮮明な同じサイズの画像が生成されます。
applyAsBase: true の場合、アップスケール結果はジョブ完成後にキャラクターのベースポートレートを自動的に置き換えます。

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

フレームレビューフロー: 生成 -> 拡張 -> アニメーション

ビデオレンダーにコミットする前に、静止フレームをレビューして拡張できます:

generate_character_frame を呼び出して、単一の静止フレームを生成します。これは { jobIds: [...] } を返します。 jobIds[0] をフレームジョブ ID として使用します。
jobIds[0] を wait_for_result でポーリングし、 get_result_image で画像をレビューします。
オプションで、フレームをアップスケールするために、 jobId: jobIds[0] を使用して enhance_character_media を呼び出します。これは新しいジョブ ID を返します。完成までポーリングします。
完成した拡張ジョブ ID に jobId を設定して animate_character を呼び出します(拡張をスキップした場合は jobIds[0])。 animate_character は任意の完成した画像ジョブをソースとして受け入れます。

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

ベースを就地で再生成

regenerate_character_base を使用して、新しいキャラクターレコードを作成せずに既存のキャラクターの新しいベースポートレート生成をキューイングします。オプションで、異なるベースプリセットに切り替えるか、同時にアイデンティティ機能を更新できます:

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

ツールは内部的にポーリングし、ジョブ完成後に新しいポートレートを自動承認し、準備完了したキャラクターオブジェクトを返します。エージェントはその後ジョブ ID をポーリングする必要がありません。