에이전트 사용하기

SimpliGen에서 에이전트가 할 수 있는 일과 경계를 유지하는 방법입니다.

View as Markdown Open in ChatGPT Open in Claude

연결한 후에는 평문으로 에이전트에게 요청하세요. 예를 들어: "SimpliGen의 이미지 프리셋을 나열한 다음 눈이 내리는 빨간 여우를 생성하고 파일을 보여줘."

에이전트가 할 수 있는 일

사용 가능한 것 확인: 생성할 수 있는 모든 프리셋(이미지 또는 비디오)과 모델이 로컬에 설치되었는지 여부를 확인합니다.
생성: 프롬프트에서 이미지 또는 비디오 작업을 시작하며, 선택적으로 참조 이미지나 시작 이미지를 포함할 수 있습니다. 로컬에서 실행되거나 SimpliGen Cloud에서 실행되거나 자동으로 선택할 수 있습니다.
작업 추적: 상태를 확인하고 결과를 기다립니다.
결과 반환: 완료된 파일 경로를 반환하거나 채팅에서 바로 이미지를 표시합니다.
프리셋 준비: 로컬 프리셋의 모델 다운로드를 시작하여 사용 준비가 되도록 합니다.
스튜디오 실행: UGC Studio와 Product Studio에 설치된 레시피를 나열하고, 입력(캐릭터, 상품, 선택지)을 채우고, 생성을 클릭한 것처럼 실행합니다. 아래의 UGC Studio와 Product Studio를 참조하세요.

로컬 대 클라우드

생성은 기본적으로 로컬에서 실행되며 크레딧을 소비하지 않습니다. 클라우드는 SimpliGen Cloud가 연결되었을 때만 제공되며, 잘 작동하는 에이전트는 크레딧을 사용하기 전에 확인하거나 실행 중인 자동 승인 모드를 따릅니다.

에이전트를 경계 내에 유지하기

지출 한도. 에이전트를 연결할 때 선택적 클라우드 지출 한도를 설정할 수 있습니다. 에이전트는 어떤 요청을 받아도 해당 한도를 초과하여 클라우드 크레딧을 사용할 수 없습니다. 로컬 생성은 항상 허용되며 한도에 포함되지 않습니다. 한도를 비워 두면 제한이 없고, 0으로 설정하면 클라우드를 완전히 차단합니다(로컬 전용).
토큰은 로컬이며 취소 가능합니다. 페어링 토큰은 자신의 머신에서 SimpliGen에만 작동하며, Connected agents에서 언제든지 취소할 수 있습니다. 취소는 즉시 적용됩니다.
앱이 제어권을 유지합니다. 에이전트는 SimpliGen과 통신하며 클라우드 계정이나 키에 직접 접근할 수 없습니다.

먼저 몇 가지 작은 작업을 실행해보세요

에이전트에게 대량의 작업을 맡기기 전에 몇 가지 단일 로컬 생성을 시도해서 요청을 어떻게 표현하고 무엇을 반환하는지 확인하세요.

에이전트가 다른 머신에서 실행되는 경우 Remote access를 참조하세요.

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은 실행을 조기에 중단합니다.

에이전트가 시작한 실행은 갤러리에 스튜디오 실행처럼 그룹화되어 표시되고 레시피의 실행 기록에 나타나므로 나중에 앱에서 다시 열거나, 재사용하거나, 다시 실행할 수 있습니다. 클라우드 실행은 시작 전에 가격이 책정되고 에이전트의 지출 한도에 포함됩니다.

에이전트는 재사용 가능한 캐릭터를 생성하고 그들로부터 장면 이미지 또는 애니메이션 비디오를 생성할 수 있습니다. 시작하기 전에 get_status를 호출하고 characters.enabled를 확인하세요: 엔진이 실행 중이고 필요한 캐릭터 프리셋이 설치되었을 때 true입니다. characters.basegenPresets과 characters.editPresets은 각 종류의 준비된 프리셋 개수를 보고합니다.

생성 경로 1: 설명

에이전트는 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'와 baseFilePath의 이미지에 대한 절대 로컬 경로로 create_character를 호출합니다. 도구는 내부적으로 업로드를 처리합니다. 생성 단계가 실행되지 않으며 캐릭터는 즉시 준비됩니다.

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

생성 경로 3: vision-recreate

에이전트(비전 포함)는 사용자 사진을 보고, 사람의 보이는 특성을 읽고, 이를 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의 파일 경로(비디오)를 사용하여 출력을 검색하세요.

참고: Character 생성은 v1에서 로컬 전용입니다. 엔진이 실행 중(get_status에서 characters.enabled: true)이어야 하고 필요한 캐릭터 프리셋이 설치되어 있어야 합니다. Character 도구에 대한 클라우드 디스패치는 지원되지 않습니다.

호출별 프리셋 전환

list_character_presets를 호출하여 설치된 프리셋과 해당 id를 확인하세요. generate_character_image와 generate_character_video에 대한 각 호출은 선택적 프리셋 재정의를 수락합니다:

generate_character_image는 identityEdit 목록의 신원-편집 프리셋 id인 presetId를 수락합니다.
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에서 사용 가능한 스케일 팩터를 나열합니다.

소스 옵션:

완료된 작업: 작업 id를 jobId에 전달하세요. 미디어 종류는 작업에서 추론됩니다.
업로드된 파일: 먼저 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: [...] }를 반환하며, 프레임 작업 id로 jobIds[0]을 사용하세요.
wait_for_result로 jobIds[0]을 폴링하고 get_result_image로 이미지를 검토하세요.
선택적으로 jobId: jobIds[0]으로 enhance_character_media를 호출하여 프레임을 업스케일하세요. 이는 새로운 작업 id를 반환하며, 완료까지 폴링하세요.
jobId를 완료된 향상 작업 id로 설정하여 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를 폴링할 필요가 없습니다.