Using an agent

View as Markdown Open in ChatGPT Open in Claude

Once connected, just ask your agent in plain language. For example: "List SimpliGen's image presets, then generate a red fox in the snow and show me the file."

What an agent can do

See what is available: every preset it can generate with, image or video, and whether the models are installed locally.
Generate: start an image or video job from a prompt, with optional reference images or a start image. It can run locally, on SimpliGen Cloud, or pick automatically.
Track jobs: check status and wait for a result.
Hand back results: return the finished file path, or show the image right in the chat.
Prepare presets: start downloading a local preset's models so it becomes ready to use.
Run the studios: list the recipes installed in UGC Studio and Product Studio, fill their inputs (a character, a product, a few choices) and run them, exactly as a click on Generate would. See UGC Studio and Product Studio below.

Generations run locally by default and never cost credits. Cloud is offered only when you have SimpliGen Cloud connected, and a well-behaved agent asks before spending credits (or follows whatever auto-approve mode you run it in).

Keeping an agent in bounds

Spend cap. When you connect an agent you can set an optional cloud spend cap. The agent can never spend more than that on cloud credits, no matter what it is asked to do. Local generation is always allowed and never counts against it. Leave the cap empty for no limit, or set it to 0 to block cloud entirely (local-only).
Tokens are local and revocable. A pairing token only works against SimpliGen on your own machine, and you can revoke it any time from Connected agents. Revoking is instant.
The app stays in control. The agent talks to SimpliGen; it cannot reach your cloud account or your key directly.

Run a few small ones first

Before handing an agent a big batch, try a couple of single local generations so you can see how it phrases requests and what it returns.

If your agent runs on a different machine, see Remote access.

UGC Studio and Product Studio

Both studios are collections of recipes: multi-step pipelines (an edit, an upscale, a video) with a small form on the front. An agent can run the same recipes through run_recipe.

Find a recipe. list_recipes returns everything installed on this device, with a category (ugc or product) and the inputs each recipe asks for: the key, its kind, whether it is required, and the allowed options for choices.
Bring the subjects. A subject input takes a character id (from list_characters) or a product id. To add a product, upload its photo with upload_file and call create_product with a name and a short description; the description is woven into the recipe's prompts.
Run it. run_recipe with the recipe id and the filled inputs. It returns a run id right away. engine is local by default when every step's preset is installed, or cloud when connected; get_recipe shows per-step readiness so the agent can tell in advance.
Wait. wait_for_recipe_run blocks until the run finishes and returns each step's result plus the final file. cancel_recipe_run stops a run early.

A run started by an agent lands in the Gallery grouped like a studio run and appears in the recipe's run history, so you can reopen, reuse, or redo it in the app afterwards. Cloud runs are priced before they start and count against the agent's spend cap.

Character Studio

An agent can create reusable characters and generate scene images or animated videos from them. Before starting, call get_status and check characters.enabled: it is true when the engine is running and the required character presets are installed. characters.basegenPresets and characters.editPresets report how many presets of each type are ready.

Creation path 1: describe

The agent calls list_character_features to get available identity features (skin tone, hair colour, eye shape, and so on), picks values for each, then calls create_character with mode: 'generate' and an identity map of { featureId: optionId }. The tool polls internally until the base portrait is ready, then returns the ready character object (with characterId and base_image_url). The agent does not need to poll a job id; the character is ready to use as soon as the tool returns. Each feature and option is keyed by its id (use this in API calls); the label on each option is a plain-English description so the agent can present choices to the user in a readable way.

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

Creation path 2: upload as base

If the user has an image they want to use directly, the agent calls create_character with mode: 'upload' and the absolute local path to the image in baseFilePath. The tool handles the upload internally. No generation step runs; the character is ready immediately.

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

Creation path 3: vision-recreate

The agent (with vision) looks at a user photo, reads the person's visible features, maps them to the options returned by list_character_features, and then follows path 1 (describe). The photo is not used as the base image. A fresh portrait is generated to recreate the look from the described features. This is useful when the user wants a stylised version of themselves or someone else rather than a photographic likeness.

Example agent reasoning flow:

User shares a photo.
Agent calls list_character_features and reviews the option ids.
Agent inspects the photo and fills an identity map: { skinTone: "light", hairColor: "red", hair: "longWaves" }.
Agent calls create_character with mode: 'generate' and the filled identity.
Tool returns the ready character object (no polling needed; it waits internally). Agent shows the base portrait to the user.

Generating scenes and videos

Once a character is ready (base accepted), pass its characterId to generate_character_image or 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"
})

Both return job ids. Use wait_for_result to poll, then get_result_image (images) or the file path from get_job (videos) to retrieve the output.

Note: Character generation is local-only in v1. The engine must be running (characters.enabled: true in get_status) and the required character presets must be installed. Cloud dispatch is not supported for character tools.

Switching presets per call

Call list_character_presets to see which presets are installed and their ids. Each call to generate_character_image and generate_character_video accepts an optional preset override:

generate_character_image accepts presetId, an identity-edit preset id from the identityEdit list.
generate_character_video accepts framePresetId (identity-edit preset for the frame step) and videoPresetId (i2v preset for the animate step).

If you omit the override, the character's sticky default is used (or the system default if none is set).

Setting a sticky per-character default

Use set_character_preset to record a default preset on a character so you do not need to pass presetId on every call:

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

Pass null for either field to clear that default:

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

Enhancing an image or video

enhance_character_media runs an upscale preset on any character asset. Before calling it, check characters.enhancePresets in get_status (or inspect the enhanceImage/enhanceVideo arrays from list_character_presets) to confirm an upscale preset is installed. Each enhancement preset lists its available scale factors in supportedScales.

Source options:

A completed job: pass the job id in jobId. The media type is inferred from the job.
An uploaded file: upload with upload_file first, then pass the handle in filePath. Include mediaType: "image" or mediaType: "video".
The character base portrait: pass target: "base". This always treats the source as an image.

Additional parameters:

scale: upscale factor (e.g. 2 or 4; must be in the preset's supportedScales).
keepResolution: if true, the result is upscaled then resized back to the original source dimensions, producing a sharper same-size image without changing the output pixel count.
applyAsBase: if true, the upscaled result replaces the character's base portrait automatically once the job completes.

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

Frame review flow: generate -> enhance -> animate

You can review and enhance a still frame before committing to the video render:

Call generate_character_frame to produce a single still frame. This returns { jobIds: [...] }; use jobIds[0] as the frame job id.
Poll jobIds[0] with wait_for_result and review the image with get_result_image.
Optionally call enhance_character_media with jobId: jobIds[0] to upscale the frame. This returns a new job id; poll it to completion.
Call animate_character with jobId set to the completed enhance job id (or jobIds[0] from the frame if you skipped enhancement). animate_character accepts any completed image job as its 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"
})

Regenerating a base in place

Use regenerate_character_base to queue a new base portrait generation for an existing character without creating a new character record. You can optionally switch to a different base preset or update the identity features at the same time:

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

The tool polls internally, auto-accepts the new portrait once the job completes, and returns the ready character object. The agent does not need to poll a job id afterward.