Einen Agent nutzen

Nach der Verbindung können Sie Ihren Agent einfach in natürlicher Sprache ansprechen. Zum Beispiel: "Liste SimpliGens Bild-Vorlagen auf, generiere dann einen roten Fuchs im Schnee und zeige mir die Datei."

Was ein Agent kann

• Verfügbare Optionen sehen: jede Vorlagen, die er generieren kann, für Bilder oder Videos, und ob die Modelle lokal installiert sind.
• Generieren: einen Bild- oder Video-Auftrag aus einer Eingabebeschreibung starten, mit optionalen Referenzbildern oder einem Startbild. Kann lokal, auf SimpliGen Cloud oder automatisch ausgewählt ausgeführt werden.
• Aufträge verfolgen: Status überprüfen und auf ein Ergebnis warten.
• Ergebnisse zurückgeben: den abgeschlossenen Dateipfad zurückgeben oder das Bild direkt im Chat anzeigen.
• Vorlagen vorbereiten: das Herunterladen der Modelle einer lokalen Vorlagen starten, damit sie bereit ist.
• Die Studios ausführen: die in UGC Studio und Product Studio installierten Rezepte auflisten, deren Eingaben ausfüllen (ein Charakter, ein Produkt, ein paar Optionen) und ausführen, genau wie ein Klick auf Generieren. Siehe UGC Studio und Product Studio unten.

Lokal versus Cloud

Generationen laufen standardmäßig lokal und kosten nie Credits. Cloud wird nur angeboten, wenn Sie SimpliGen Cloud verbunden haben, und ein gut funktionierender Agent fragt nach, bevor er Credits ausgibt (oder folgt dem Auto-Genehmigungsmodus, in dem Sie ihn ausführen).

Einen Agent kontrollieren

• Ausgabenlimit. Wenn Sie einen Agent verbinden, können Sie ein optionales Cloud-Ausgabenlimit festlegen. Der Agent kann auf Cloud-Credits niemals mehr als dieses Limit ausgeben, unabhängig davon, worum er gebeten wird. Lokale Generierung ist immer erlaubt und zählt nie dagegen. Lassen Sie das Limit leer für keine Grenze, oder setzen Sie es auf 0, um Cloud vollständig zu blockieren (nur lokal).
• Token sind lokal und widerrufbar. Ein Pairing-Token funktioniert nur gegen SimpliGen auf Ihrem eigenen Computer, und Sie können ihn jederzeit unter Verbundene Agenten widerrufen. Das Widerrufen ist sofort.
• Die App bleibt in Kontrolle. Der Agent spricht mit SimpliGen; er kann nicht direkt auf Ihr Cloud-Konto oder Ihren Schlüssel zugreifen.

Wenn Ihr Agent auf einem anderen Computer läuft, siehe Fernzugriff.

UGC Studio und Product Studio

Beide Studios sind Sammlungen von Rezepten: mehrstufige Pipelines (eine Bearbeitung, eine Hochskalierung, ein Video) mit einem kleinen Formular vorne. Ein Agent kann die gleichen Rezepte über run_recipe ausführen.

1. Ein Rezept finden. list_recipes gibt alles zurück, was auf diesem Gerät installiert ist, mit einer category (ugc oder product) und den inputs, die jedes Rezept verlangt: der Schlüssel, seine Art, ob es erforderlich ist, und die erlaubten Optionen für Auswahlen.
2. Die Subjekte bringen. Eine subject-Eingabe nimmt eine Charakter-ID (aus list_characters) oder eine Produkt-ID. Um ein Produkt hinzuzufügen, laden Sie sein Foto mit upload_file hoch und rufen create_product mit einem Namen und einer kurzen Beschreibung auf; die Beschreibung wird in die Aufforderungen des Rezepts eingewoben.
3. Ausführen. run_recipe mit der Rezept-ID und den ausgefüllten Eingaben. Es gibt sofort eine Lauf-ID zurück. engine ist standardmäßig local, wenn jede Vorlagen des Schritts installiert ist, oder cloud, wenn verbunden; get_recipe zeigt die Bereitschaft pro Schritt, damit der Agent sie im Voraus erkennen kann.
4. Warten. wait_for_recipe_run blockiert, bis der Lauf beendet ist, und gibt die Ergebnisse jedes Schritts plus die endgültige Datei zurück. cancel_recipe_run beendet einen Lauf früh.

Ein von einem Agent gestarteter Lauf landet in der Galerie, gruppiert wie ein Studio-Lauf, und wird in der Laufhistorie des Rezepts angezeigt, damit Sie ihn später in der App erneut öffnen, wiederverwenden oder wiederholen können. Cloud-Läufe werden vor dem Start bepreist und zählen gegen das Ausgabenlimit des Agenten.

Character Studio

Ein Agent kann wiederverwendbare Charaktere erstellen und Szenenbilder oder animierte Videos aus ihnen generieren. Rufen Sie zuerst get_status auf und überprüfen Sie characters.enabled: es ist true, wenn die Engine läuft und die erforderlichen Charakter-Vorlagen installiert sind. characters.basegenPresets und characters.editPresets melden, wie viele Vorlagen jedes Typs bereit sind.

Erstellungspfad 1: beschreiben

Der Agent ruft list_character_features auf, um verfügbare Identitätsmerkmale (Hautton, Haarfarbe, Augenschnitt usw.) zu erhalten, wählt Werte für jeden aus, ruft dann create_character mit mode: 'generate' und einer identity-Zuordnung von { featureId: optionId } auf. Das Tool pollt intern, bis das Basisporträt bereit ist, und gibt das fertige Charakterobjekt zurück (mit characterId und base_image_url). Der Agent muss keine Job-ID abfragen; der Charakter ist einsatzbereit, sobald das Tool zurückkehrt. Jedes Merkmal und jede Option wird durch seine id gekennzeichnet (verwenden Sie diese bei API-Aufrufen); das label auf jeder Option ist eine einfache englische Beschreibung, damit der Agent Auswahlen dem Benutzer lesbar präsentieren kann.

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

Erstellungspfad 2: als Basis hochladen

Wenn der Benutzer ein Bild hat, das er direkt verwenden möchte, ruft der Agent create_character mit mode: 'upload' und dem absoluten lokalen Pfad zum Bild in baseFilePath auf. Das Tool bearbeitet den Upload intern. Es wird kein Generierungsschritt ausgeführt; der Charakter ist sofort bereit.

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

Erstellungspfad 3: vision-recreate

Der Agent (mit Vision) schaut sich ein Benutzerfoto an, liest die sichtbaren Merkmale der Person, ordnet sie den Optionen zu, die von list_character_features zurückgegeben werden, und folgt dann Pfad 1 (beschreiben). Das Foto wird nicht als Basisbild verwendet. Ein neues Porträt wird generiert, um das Aussehen von den beschriebenen Merkmalen zu reproduzieren. Dies ist nützlich, wenn der Benutzer eine stilisierte Version von sich selbst oder jemand anderem anstelle einer fotografischen Ähnlichkeit möchte.

Beispiel-Agent-Reasoning-Flow:

1. Benutzer teilt ein Foto.
2. Agent ruft list_character_features auf und überprüft die Optionen-IDs.
3. Agent inspiziert das Foto und füllt eine identity-Zuordnung aus: { skinTone: "light", hairColor: "red", hair: "longWaves" }.
4. Agent ruft create_character mit mode: 'generate' und der ausgefüllten identity auf.
5. Tool gibt das fertige Charakterobjekt zurück (kein Polling erforderlich; es wartet intern). Agent zeigt das Basisporträt dem Benutzer.

Szenen und Videos generieren

Sobald ein Charakter bereit ist (Basis akzeptiert), übergeben Sie seine characterId an generate_character_image oder 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"
})

Beide geben Job-IDs zurück. Verwenden Sie wait_for_result zum Abfragen, dann get_result_image (Bilder) oder den Dateipfad von get_job (Videos), um die Ausgabe abzurufen.

Hinweis: Charaktergenerierung ist in v1 nur lokal. Die Engine muss laufen (characters.enabled: true in get_status) und die erforderlichen Charakter-Vorlagen müssen installiert sein. Cloud-Versand wird für Charakter-Tools nicht unterstützt.

Vorlagen pro Aufruf wechseln

Rufen Sie list_character_presets auf, um zu sehen, welche Vorlagen installiert sind und ihre IDs. Jeder Aufruf von generate_character_image und generate_character_video akzeptiert eine optionale Vorlagen-Überschreibung:

• generate_character_image akzeptiert presetId, eine Identitäts-Edit-Vorlagen-ID aus der identityEdit-Liste.
• generate_character_video akzeptiert framePresetId (Identitäts-Edit-Vorlagen für den Frame-Schritt) und videoPresetId (i2v-Vorlagen für den Animationsschritt).

Wenn Sie die Überschreibung weglassen, wird die sticky Standard-Vorlagen des Charakters verwendet (oder die System-Standard, wenn keine gesetzt ist).

Standard pro Charakter festlegen

Verwenden Sie set_character_preset, um einen Standard-Preset auf einem Charakter zu verzeichnen, damit Sie presetId nicht bei jedem Aufruf übergeben müssen:

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

Übergeben Sie null für eines der Felder, um diesen Standard zu löschen:

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

Ein Bild oder Video verbessern

enhance_character_media führt eine Hochskalierungs-Vorlagen auf einem beliebigen Charakterasset aus. Überprüfen Sie vorher characters.enhancePresets in get_status (oder inspizieren Sie die enhanceImage/enhanceVideo-Arrays von list_character_presets), um zu bestätigen, dass eine Hochskalierungs-Vorlagen installiert ist. Jede Verbesserungs-Vorlagen listet ihre verfügbaren Skalierungsfaktoren in supportedScales auf.

Quellenoptionen:

• Ein abgeschlossener Job: übergeben Sie die Job-ID in jobId. Der Medientyp wird aus dem Job abgeleitet.
• Eine hochgeladene Datei: laden Sie zuerst mit upload_file hoch, übergeben Sie dann das Handle in filePath. Fügen Sie mediaType: "image" oder mediaType: "video" ein.
• Das Charakter-Basisporträt: übergeben Sie target: "base". Dies behandelt die Quelle immer als Bild.

Zusätzliche Parameter:

• scale: Hochskalierungsfaktor (z.B. 2 oder 4; muss in den supportedScales der Vorlagen sein).
• keepResolution: wenn true, wird das Ergebnis hochskaliert und dann auf die ursprünglichen Quelldimensionen zurückgeändert, wodurch ein schärferes Bild in der gleichen Größe ohne Änderung der Ausgabepixelzahl entsteht.
• applyAsBase: wenn true, ersetzt das hochskalierte Ergebnis automatisch das Basisporträt des Charakters, sobald der Job abgeschlossen ist.

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: generieren → verbessern → animieren

Sie können einen einzelnen Frame überprüfen und verbessern, bevor Sie das Video-Rendering committen:

1. Rufen Sie generate_character_frame auf, um einen einzelnen Frame zu erzeugen. Dies gibt { jobIds: [...] } zurück; verwenden Sie jobIds[0] als Frame-Job-ID.
2. Fragen Sie jobIds[0] mit wait_for_result ab und überprüfen Sie das Bild mit get_result_image.
3. Rufen Sie optional enhance_character_media mit jobId: jobIds[0] auf, um den Frame hochzuskalieren. Dies gibt eine neue Job-ID zurück; fragen Sie sie zum Abschluss ab.
4. Rufen Sie animate_character mit jobId auf, das auf die abgeschlossene Enhance-Job-ID gesetzt ist (oder jobIds[0] aus dem Frame, wenn Sie die Verbesserung übersprungen haben). animate_character akzeptiert jeden abgeschlossenen Image-Job als Quelle.

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

Basis an Ort und Stelle regenerieren

Verwenden Sie regenerate_character_base, um eine neue Basisporträt-Generierung für einen vorhandenen Charakter in die Warteschlange zu stellen, ohne einen neuen Charakterdatensatz zu erstellen. Sie können optional gleichzeitig zu einer anderen Basis-Vorlagen wechseln oder die Identitätsmerkmale aktualisieren:

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

Das Tool pollt intern, akzeptiert das neue Porträt automatisch, sobald der Job abgeschlossen ist, und gibt das fertige Charakterobjekt zurück. Der Agent muss danach keine Job-ID abfragen.