使用代理

View as Markdown Open in ChatGPT Open in Claude

连接后，只需用纯自然语言向代理提出请求。例如："列出SimpliGen的图像预设，然后生成一只雪地里的红狐狸，并给我显示这个文件。"

代理可以做什么

查看可用资源： 它能生成的每个预设（图像或视频），以及模型是否在本地安装。
生成： 从提示词启动图像或视频任务，可选参考图像或开始图像。可以在本地运行、在SimpliGen Cloud上运行，或自动选择。
跟踪任务： 检查状态并等待结果。
返回结果： 返回完成的文件路径，或直接在聊天中显示图像。
准备预设： 开始下载本地预设的模型，使其可以使用。
运行工作室： 列出UGC Studio和Product Studio中安装的配方，填充其输入（角色、产品、几个选择），并运行它们，就像点击"生成"一样。见下文UGC Studio和Product Studio。

本地与云

生成默认在本地运行，不消耗任何积分。仅当SimpliGen Cloud已连接时才提供云选项，行为规范的代理会在消费积分前询问（或按你设置的自动批准模式运行）。

对代理设置限制

支出上限。 连接代理时，你可以设置可选的云支出上限。无论代理被要求做什么，都无法超过该上限消费云积分。本地生成始终允许且不计入上限。留空表示无限制，或设置为0以完全阻止云生成（仅限本地）。
令牌是本地的且可撤销。 配对令牌仅对你自己机器上的SimpliGen有效，你可以随时从已连接的代理中撤销它。撤销是即时的。
应用保持控制。 代理与SimpliGen通信；它无法直接访问你的云账户或密钥。

先运行几个小的

在给代理分配大批任务前，试试几个单独的本地生成，这样你可以看到它如何表述请求以及它返回什么。

如果代理运行在不同的机器上，见远程访问。

UGC Studio和Product Studio

两个工作室都是配方集合：多步骤管道（编辑、放大、视频），前面有一个小表单。代理可以通过run_recipe运行相同的配方。

找到配方。 list_recipes返回此设备上安装的所有配方，包括category（ugc或product）和每个配方要求的inputs：键、类型、是否必需，以及选择的允许选项。
提供主体。 subject输入接受角色id（来自list_characters）或产品id。要添加产品，先用upload_file上传其照片，然后用名称和简短描述调用create_product；描述会被编织到配方的提示词中。
运行它。 用配方id和已填充的输入调用run_recipe。它立即返回一个运行id。当每个步骤的预设都已安装时engine默认为local，或在已连接时为cloud；get_recipe显示逐步就绪状态，以便代理可以提前判断。
等待。 wait_for_recipe_run阻塞直到运行完成，返回每个步骤的结果和最终文件。cancel_recipe_run提前停止运行。

由代理启动的运行会进入Gallery，分组方式与工作室运行相同，并出现在配方的运行历史中，因此你之后可以在应用中重新打开、重用或重做它。云运行在开始前定价，并计入代理的支出上限。

Character Studio

代理可以创建可复用的角色，并从他们生成场景图像或动画视频。开始前，调用get_status并检查characters.enabled：当引擎运行且必需的角色预设已安装时为true。characters.basegenPresets和characters.editPresets报告每种类型有多少个预设已就绪。

代理调用list_character_features获取可用的身份特征（肤色、发色、眼睛形状等），为每个特征选择值，然后用mode: 'generate'和{ featureId: optionId }的identity映射调用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。
代理检查照片并填充identity映射：{ skinTone: "light", hairColor: "red", hair: "longWaves" }。
代理用mode: 'generate'和已填充的identity调用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。
用wait_for_result轮询jobIds[0]并用get_result_image审查图像。
可选地用jobId: jobIds[0]调用enhance_character_media以放大帧。这返回新的任务id；轮询它直到完成。
用jobId设置为已完成的增强任务id（或如果跳过增强则为帧的jobIds[0]）调用animate_character。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" }
})