Uso de un agente

Una vez conectado, simplemente pregunta a tu agente en lenguaje natural. Por ejemplo: "Lista los presets de imagen de SimpliGen, luego genera un zorro rojo en la nieve y muéstrame el archivo."

Qué puede hacer un agente

• Ver qué está disponible: cada preset con el que puede generar, imagen o vídeo, y si los modelos están instalados localmente.
• Generar: iniciar un trabajo de imagen o vídeo a partir de un prompt, con imágenes de referencia opcionales o una imagen de inicio. Puede ejecutarse localmente, en SimpliGen Cloud, o elegir automáticamente.
• Rastrear trabajos: verificar el estado y esperar un resultado.
• Devolver resultados: retornar la ruta del archivo terminado o mostrar la imagen directamente en el chat.
• Preparar presets: comenzar a descargar los modelos de un preset local para que esté listo para usar.
• Ejecutar los estudios: listar las recetas instaladas en UGC Studio y Product Studio, rellenar sus entradas (un personaje, un producto, algunas opciones) y ejecutarlas, exactamente como al hacer clic en Generar. Ver UGC Studio y Product Studio abajo.

Local vs cloud

Las generaciones se ejecutan localmente por defecto y nunca cuestan créditos. Cloud se ofrece solo cuando tienes SimpliGen Cloud conectado, y un agente bien comportado pregunta antes de gastar créditos (o sigue cualquier modo de aprobación automática en el que lo ejecutes).

Mantener un agente dentro de los límites

• Límite de gasto. Cuando conectas un agente puedes establecer un límite de gasto en cloud opcional. El agente nunca puede gastar más que eso en créditos de cloud, sin importar lo que se le pida. La generación local siempre está permitida y nunca cuenta contra él. Deja el límite vacío para sin límite, o establécelo a 0 para bloquear cloud completamente (solo local).
• Los tokens son locales y revocables. Un token de emparejamiento solo funciona contra SimpliGen en tu propia máquina, y puedes revocarlo en cualquier momento desde Agentes conectados. La revocación es instantánea.
• La app mantiene el control. El agente se comunica con SimpliGen, no puede acceder directamente a tu cuenta cloud ni a tu clave.

Si tu agente se ejecuta en una máquina diferente, ver Acceso remoto.

UGC Studio y Product Studio

Ambos estudios son colecciones de recetas: pipelines multietapa (una edición, un upscale, un vídeo) con un pequeño formulario al frente. Un agente puede ejecutar las mismas recetas a través de run_recipe.

1. Encuentra una receta. list_recipes devuelve todo lo instalado en este dispositivo, con una category (ugc o product) y los inputs que cada receta solicita: la clave, su tipo, si es obligatoria, y las opciones permitidas para las selecciones.
2. Aporta los sujetos. Una entrada subject toma un id de personaje (de list_characters) o un id de producto. Para agregar un producto, carga su foto con upload_file y llama a create_product con un nombre y una breve descripción; la descripción se teje en los prompts de la receta.
3. Ejecútala. run_recipe con el id de la receta y las entradas rellenadas. Devuelve un id de ejecución inmediatamente. engine es local por defecto cuando cada preset del paso está instalado, o cloud cuando está conectado; get_recipe muestra la disponibilidad por paso para que el agente pueda saberlo de antemano.
4. Espera. wait_for_recipe_run se bloquea hasta que la ejecución finaliza y devuelve el resultado de cada paso más el archivo final. cancel_recipe_run detiene una ejecución anticipadamente.

Una ejecución iniciada por un agente llega a la Galería agrupada como una ejecución de estudio y aparece en el historial de ejecución de la receta, para que puedas reabrirla, reutilizarla o hacerla de nuevo en la app después. Las ejecuciones en cloud se cotizan antes de comenzar y cuentan contra el límite de gasto del agente.

Character Studio

Un agente puede crear personajes reutilizables y generar imágenes de escenas o vídeos animados de ellos. Antes de comenzar, llama a get_status y verifica characters.enabled: es true cuando el motor está ejecutándose y los presets de personaje requeridos están instalados. characters.basegenPresets y characters.editPresets informan cuántos presets de cada tipo están listos.

Ruta de creación 1: describir

El agente llama a list_character_features para obtener características de identidad disponibles (tono de piel, color de cabello, forma de ojos, etc.), elige valores para cada una, luego llama a create_character con mode: 'generate' y un mapa identity de { featureId: optionId }. La herramienta inspecciona internamente hasta que el retrato base está listo, luego devuelve el objeto de personaje listo (con characterId y base_image_url). El agente no necesita inspeccionar un id de trabajo; el personaje está listo para usar tan pronto como la herramienta devuelve. Cada característica y opción se codifica por su id (úsalo en llamadas API); el label en cada opción es una descripción en inglés plano para que el agente pueda presentar opciones al usuario de una manera legible.

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

Ruta de creación 2: cargar como base

Si el usuario tiene una imagen que desea usar directamente, el agente llama a create_character con mode: 'upload' y la ruta local absoluta de la imagen en baseFilePath. La herramienta maneja la carga internamente. No se ejecuta ningún paso de generación; el personaje está listo inmediatamente.

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

Ruta de creación 3: vision-recreate

El agente (con visión) mira una foto del usuario, lee las características visibles de la persona, las mapea a las opciones devueltas por list_character_features, y luego sigue la ruta 1 (describir). La foto no se utiliza como imagen base. Se genera un retrato nuevo para recrear el aspecto a partir de las características descritas. Esto es útil cuando el usuario desea una versión estilizada de sí mismo u otra persona en lugar de un parecido fotográfico.

Ejemplo de flujo de razonamiento del agente:

1. El usuario comparte una foto.
2. El agente llama a list_character_features y revisa los ids de opción.
3. El agente inspecciona la foto y rellena un mapa identity: { skinTone: "light", hairColor: "red", hair: "longWaves" }.
4. El agente llama a create_character con mode: 'generate' y el identity rellenado.
5. La herramienta devuelve el objeto de personaje listo (sin inspección necesaria; espera internamente). El agente muestra el retrato base al usuario.

Generación de escenas y vídeos

Una vez que un personaje está listo (base aceptada), pasa su 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"
})

Ambas devuelven ids de trabajo. Usa wait_for_result para inspeccionar, luego get_result_image (imágenes) o la ruta del archivo de get_job (vídeos) para recuperar la salida.

Nota: La generación de personajes es solo local en v1. El motor debe estar ejecutándose (characters.enabled: true en get_status) y los presets de personaje requeridos deben estar instalados. El envío en cloud no es compatible para herramientas de personaje.

Cambiar presets por llamada

Llama a list_character_presets para ver qué presets están instalados y sus ids. Cada llamada a generate_character_image y generate_character_video acepta una anulación de preset opcional:

• generate_character_image acepta presetId, un id de preset de edición de identidad de la lista identityEdit.
• generate_character_video acepta framePresetId (preset de edición de identidad para el paso de fotograma) y videoPresetId (preset i2v para el paso de animación).

Si omites la anulación, se usa el default pegajoso del personaje (o el default del sistema si ninguno está establecido).

Establecer un default pegajoso por personaje

Usa set_character_preset para registrar un preset default en un personaje para que no necesites pasar presetId en cada llamada:

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

Pasa null para cualquier campo para borrar ese default:

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

Mejorar una imagen o vídeo

enhance_character_media ejecuta un preset de upscale en cualquier recurso de personaje. Antes de llamarlo, verifica characters.enhancePresets en get_status (o inspecciona los arrays enhanceImage/enhanceVideo de list_character_presets) para confirmar que un preset de upscale está instalado. Cada preset de mejora lista sus factores de escala disponibles en supportedScales.

Opciones de origen:

• Un trabajo completado: pasa el id del trabajo en jobId. El tipo de media se infiere del trabajo.
• Un archivo cargado: carga primero con upload_file, luego pasa el identificador en filePath. Incluye mediaType: "image" o mediaType: "video".
• El retrato base del personaje: pasa target: "base". Esto siempre trata el origen como una imagen.

Parámetros adicionales:

• scale: factor de upscale (ej. 2 o 4; debe estar en supportedScales del preset).
• keepResolution: si es true, el resultado se upscalea luego se redimensiona a las dimensiones originales de la fuente, produciendo una imagen más nítida del mismo tamaño sin cambiar el número de píxeles de salida.
• applyAsBase: si es true, el resultado upscaleado reemplaza automáticamente el retrato base del personaje una vez que el trabajo se 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
})

Flujo de revisión de fotograma: generar -> mejorar -> animar

Puedes revisar y mejorar un fotograma fijo antes de comprometerte con el renderizado de vídeo:

1. Llama a generate_character_frame para producir un solo fotograma fijo. Esto devuelve { jobIds: [...] }; usa jobIds[0] como el id del trabajo de fotograma.
2. Inspecciona jobIds[0] con wait_for_result y revisa la imagen con get_result_image.
3. Opcionalmente llama a enhance_character_media con jobId: jobIds[0] para upscalear el fotograma. Esto devuelve un nuevo id de trabajo; inspecciona su completación.
4. Llama a animate_character con jobId establecido al id del trabajo de mejora completado (o jobIds[0] del fotograma si omitiste la mejora). animate_character acepta cualquier trabajo de imagen completado como su origen.

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

Regenerar una base en su lugar

Usa regenerate_character_base para poner en cola una nueva generación de retrato base para un personaje existente sin crear un nuevo registro de personaje. Opcionalmente puedes cambiar a un preset base diferente o actualizar las características de identidad al mismo tiempo:

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

La herramienta inspecciona internamente, auto-acepta el nuevo retrato una vez que el trabajo se completa, y devuelve el objeto de personaje listo. El agente no necesita inspeccionar un id de trabajo después.