Higgsfield 생성은(는) 무엇을 하나요?

모든 Higgsfield 모델에 작업을 제출합니다. higgsfield CLI를 래핑합니다. 일반 이미지/비디오 생성 및 Marketing Studio(브랜드 광고, 아바타, 제품, 훅, 설정)를 포함합니다.

0단계 — 부트스트랩

다른 명령보다 먼저 CLI가 설치되고 인증되었는지 확인하세요:

higgsfield이(가) $PATH에 없는 경우, 설치하세요:

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

higgsfield account status가 Session expired / Not authenticated로 실패하면, 사용자에게 higgsfield auth login(대화형, 브라우저 열림)을 실행하도록 요청하고 계속하기 전에 사용자가 확인할 때까지 기다리세요.

higgsfield account status가 이미 계정 정보를 출력한다면 두 검사를 모두 건너뛰세요.

UX 규칙

간결하게 하세요. 채팅에 원시 ID나 JSON 덤프를 표시하지 마세요. 준비가 되면 결과 URL을 출력하세요.
내부 전문 용어를 사용하지 마세요. "higgsfield 비용 호출 중", "작업 폴링 중"과 같이 설명하지 마세요.
첫 메시지에서 사용자의 언어를 감지하고 해당 언어로 응답하세요. 기술적 인수(--aspect_ratio 16:9)는 영어로 유지됩니다.
일괄 질문하지 마세요. 합리적인 기본 모델을 선택하고, 정말로 누락된 경우에만 한 번에 한 가지만 질문하세요.
비용을 미리 추정하지 마세요. 사용자가 묻지 않는 한 그냥 제출하세요.
generate create에 --wait을 전달하여 명령이 완료될 때까지 차단되고 결과 URL을 자체적으로 출력하도록 하세요. 두 단계(create → wait) 패턴을 피하세요.

워크플로우 — 일반 생성

모델 선택. 실제 사용 사례에 따른 실용적인 기본값:

이미지:
- 브랜드 제품 비주얼(핀터레스트 핀, 라이프스타일, 히어로 배너, 광고 팩, 가상 체험) → 이 스킬이 아닌 higgsfield-product-photoshoot을 사용하세요.
- 아바타 + 제품이 있는 브랜드 광고 이미지(Marketing Studio 형태) → Marketing Studio 이미지(Marketing Studio 참조)
- 미적인 UGC / 패션 에디토리얼 / 라이프스타일 캐릭터 → Soul 2.0
- 영화 같은 스틸 프레임 → Soul Cinema
- 개성이 강한 창의적 인물(텍스트 전용, 독특함) → Soul Cast
- 장소 / 환경 / 사람 없는 장면 → Soul Location (최고 수준)
- 벡터 일러스트레이션 또는 얼굴 편집 + 복잡한 장면 변환 → Seedream 4.5
- Soul 캐릭터(higgsfield-soul-id의 참조 ID 사용) → 스틸의 경우 Soul 2.0, 영화 같은 경우 Soul Cinema
- 빠르고 저렴한 반복 → Z Image
- 캐릭터 또는 만화 스타일 작업 → Nano Banana 2; 어려운 경우 Nano Banana Pro로 업그레이드
- 그 외 모든 경우 기본값 → GPT Image 2. 그래픽 디자인, UI, 배너, 타이포그래피 및 고충실도 일반 생성.
비디오:
- 모든 광고 / 상업 / 브랜드 광고 비디오 → Marketing Studio(Marketing Studio 참조)
- 기본 다목적 진지한 비디오(다중 샷, 일관된 아이덴티티, 움직임 중심) → Seedance 2.0. 최고 수준.
- 강한 역동성이 없는 단일 평면 장면, Seedance 2.0보다 저렴함 → Kling 3.0
- 컷 없이 저렴하고 깔끔한 샷 → Seedance 1.5 Pro
- 시네마급 최고 충실도 → Cinema Studio Video 3.0
- 강력한 물리 효과와 함께 저렴하고 오디오 불필요 → Minimax Hailuo
- 빠른 배치 / 볼륨 → Veo 3.1 Lite
higgsfield generate create에 전달할 실제 --model ID는 higgsfield model list --json | jq를 실행하여 표시 이름을 ID에 매핑하세요. 전체 테이블은 references/model-catalog.md를 참조하세요.
미디어 입력을 플래그로 직접 전달하세요. 미디어 플래그는 로컬 파일 경로 또는 UUID를 허용합니다. CLI는 경로를 자동으로 업로드하고 UUID에 대한 작업 vs 업로드를 자동 감지합니다. 사전 업로드가 필요하지 않습니다. 각 모델은 허용되는 역할(image, start_image, end_image, video, audio)을 선언합니다 — references/media-inputs.md를 참조하세요.
빠르게 검증하세요. 매개변수가 확실하지 않으면 higgsfield model get <jst> --json을 한 번 실행하고 필요한 것만 전달하세요. 그 외에는 스키마 기본값을 사용하세요. 서버는 비치명적 강제 변환(예: aspect_ratio=99:99 → 가장 가까운 일치)에 대한 adjustments와 유효하지 않은 선언된 매개변수 값에 대한 구조화된 오류를 반환합니다.
한 번에 제출하고 대기하세요. higgsfield generate create <jst> --prompt "..." [미디어 플래그] [매개변수 플래그] --wait. 최종 상태까지 차단되고 결과 URL을 stdout에 출력합니다. 설정 가능: --wait-timeout 20m(기본 10m), --wait-interval 5s(기본 3s).
전달. URL과 한 줄 요약(모델, 비디오인 경우 길이)을 보내세요.

나중에 검사하거나 재실행하려면 higgsfield generate list --json 및 higgsfield generate get <id> --json으로 회고할 수 있습니다. --wait 없이 시작된 작업에 다시 참여해야 하는 경우 higgsfield generate wait <id>를 계속 사용할 수 있습니다.

미디어 플래그

플래그	용도	이를 허용하는 모델
`--image <경로-또는-ID>`	참조 이미지	대부분의 이미지 모델, `seedance_2_0`, `veo3`, `marketing_studio_video`
`--start-image <경로-또는-ID>`	이미지-비디오 전환의 첫 프레임	`kling3_0`, `kling2_6`, `veo3_1`, `seedance_2_0`, `marketing_studio_video`
`--end-image <경로-또는-ID>`	전환의 마지막 프레임	`kling3_0`, `seedance_2_0`, `marketing_studio_video`
`--video <경로-또는-ID>`	참조 비디오	`seedance_2_0`
`--audio <경로-또는-ID>`	참조 오디오(립싱크, 사운드트랙 일치)	`seedance_2_0` (`--generate-audio`가 아닌 이것을 사용하세요)

각 플래그는 로컬 파일 경로(자동 업로드됨) 또는 UUID(업로드 생성 시 higgsfield upload create의 ID 또는 이전 작업 ID)를 허용합니다. 각 모델은 MEDIA_ROLES을 통해 자체 역할 집합을 선언합니다. 전체 테이블은 references/media-inputs.md를 참조하세요.

일반 매개변수

플래그는 모델 스키마를 통해 전달됩니다. higgsfield model get <jst>를 사용하여 발견하세요.

higgsfield generate create gpt_image_2 --prompt "황혼의 네온 시티" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "애니메이션 캐릭터 컨셉, 표현력 있는 포즈" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "카메라가 안으로 돌리인다" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

기계가 읽을 수 있는 출력(연결된 파이프라인, 에이전트 컨텍스트)을 위해 --json을 추가하세요. --wait --json을 사용하면 최종 작업 객체 배열을 얻습니다. --wait 없이 작업 ID를 얻습니다.

Stdin 프롬프트: echo "..." | higgsfield generate create z_image --wait.

Soul 이미지 품질: text2image_soul_v2 및 soul_cinematic의 경우 --quality 1.5k 또는 --quality 2k를 전달하세요. 이는 UI용 계층이며 백엔드는 이를 선택된 --aspect_ratio의 720p/1080p 및 모델별 치수에 매핑합니다. soul_location에는 품질 선택기가 없습니다. 종횡비당 고정 치수를 사용합니다.

Marketing Studio

브랜드 이미지/비디오 생성: 아바타 + 제품 + 선택적 설정 훅/설정 + 광고 스타일 모드. marketing_studio_video 및 marketing_studio_image 모델을 사용합니다.

개념

아바타 — 발표자 얼굴. 선별된 preset(higgsfield marketing-studio avatars list로 찾아보기) 또는 custom(higgsfield marketing-studio avatars create를 통해 업로드된 사진). UGC 모드의 경우, 브리핑에 사람이 명확히 언급된 경우 아바타는 선택 사항입니다. 백엔드가 자동으로 Soul 캐릭터를 생성할 수 있습니다. 사용자가 특정 발표자를 원할 때 아바타를 전달하세요.
제품 — 제목 + 참조 이미지가 있는 브랜드 아이템. URL에서 가져오기(higgsfield marketing-studio products fetch --url ...) 또는 업로드된 이미지에서 생성(higgsfield marketing-studio products create).
웹 제품 — 앱 스토어 / 웹 페이지 버전. 앱 스토어 URL을 가져올 때 자동 라우팅됩니다.
훅 — 재사용 가능한 오프닝 앵글 / 광고 훅. higgsfield marketing-studio hooks list로 찾아보세요. 훅 텍스트는 사용자의 프롬프트 앞에 추가됩니다. --prompt를 대체하지 않습니다.
설정 — 재사용 가능한 환경 / 장면 컨텍스트. higgsfield marketing-studio settings list로 찾아보세요.

발견 명령어

사용자가 무엇이 이미 존재하는지 물을 때 다음 정확한 목록 명령어를 사용하세요:

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json

--hook_id 및 --setting_id는 marketing_studio_video에서만 지원됩니다. marketing_studio_image에 전달하지 마세요.

UX 규칙 (추가)

한 단계에 하나의 질문만 하세요. 제품+아바타+모드를 한꺼번에 묻지 마세요.

워크플로우 — 빠른 광고 비디오

제품 가져오기.
- 기존 제품 → higgsfield marketing-studio products list --json
- URL → higgsfield marketing-studio products fetch --url <url> --wait (임포트가 완료될 때까지 폴링)
- 로컬 이미지 → higgsfield upload create <photo>... 그 다음 higgsfield marketing-studio products create --title "..." --image <id>... 제품 ID를 캡처하세요. --hook_id를 사용할 때는 --product_ids를 전달하는 것을 적극 권장합니다. 훅은 제품을 중심으로 전환하도록 설계되었으며 제품 컨텍스트 없이는 제대로 작동하지 않습니다.
필요한 경우 아바타 선택.
- 기본값: higgsfield marketing-studio avatars list를 실행하고 브랜드 음성에 맞는 프리셋을 선택하세요.
- 맞춤: higgsfield marketing-studio avatars create --name "..." --image <upload_id>. UGC 모드의 경우, 특정 발표자가 필요하지 않고 브리핑에 사람이 언급된 경우 --avatars를 생략할 수 있습니다. 백엔드가 Soul 캐릭터를 합성할 수 있습니다.
선택적으로 설정 항목 선택.
- 훅: higgsfield marketing-studio hooks list --json
- 설정: higgsfield marketing-studio settings list --json 선택된 ID를 marketing_studio_video에만 --hook_id <hook_id> 및 --setting_id <setting_id>로 전달하세요. 사용자가 명시적으로 동일한 문구를 강화하려는 경우가 아니라면 훅의 프롬프트를 --prompt에 복사하지 마세요.
필요한 경우 모드 선택. 기본값은 ugc입니다. --hook_id가 있다고 해서 --mode가 필수는 아닙니다. 다른 현재 슬러그: ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. references/marketing-modes.md를 참조하세요.
생성(원샷).
```
PRODUCT_IDS_JSON=$(mktemp)
AVATARS_JSON=$(mktemp)
printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"

higgsfield generate create marketing_studio_video \
  --prompt "..." \
  --avatars @"$AVATARS_JSON" \
  --product_ids @"$PRODUCT_IDS_JSON" \
  --mode ugc \
  --duration 15 \
  --resolution 720p \
  --aspect_ratio 9:16 \
  --wait
```
설정 훅/설정이 선택된 경우 --hook_id <hook_id> 및/또는 --setting_id <setting_id>를 추가하세요. product_ids 및 avatars는 JSON 배열입니다. @/path/to/file.json을 통해 전달하세요. --product_ids에 단순 UUID를 전달하지 마세요. 해상도는 480p 또는 720p입니다. 종횡비는 auto/21:9/16:9/4:3/1:1/3:4/9:16 중 하나입니다. --generate-audio true가 여기서 지원됩니다(seedance_2_0과 달리). --wait는 완료될 때까지 차단됩니다. 더 긴 광고 실행을 위해 --wait-timeout 30m을 늘리세요.
전달. URL + 한 줄 요약(모드, 길이).

클릭-투-광고 바로가기 (URL 기반)

사용자가 제품 URL을 제공하고 한 번에 마케팅 비디오를 원할 때:

# 1. 가져오기 트리거 (제품 ID를 반환하고 백그라운드 스크래핑 시작)
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. 동일한 URL에 대해 마케팅 비디오 생성 — 백엔드는 엔티티를 재사용
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

백엔드는 URL별로 중복을 제거하므로 반복 실행 시 다시 가져오는 대신 기존 엔티티를 재사용합니다.

워크플로우 — 마케팅 이미지

위와 동일하지만 marketing_studio_image 모델을 사용하세요:

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

오류

Missing required params: prompt → 사용자가 프롬프트를 제공하지 않음. 요청하세요.
Invalid values: aspect_ratio=99:99 (allowed: ...) → 잘못된 열거형. 허용된 목록에서 선택하세요.
Unknown params: foo → 스키마가 해당 플래그를 허용하지 않음. higgsfield model get <jst>를 확인하세요. hook_id 또는 setting_id에서 이 문제가 발생하면 선택한 모델/작업_설정_유형이 Marketing Studio 설정 항목을 지원하지 않는 것입니다.
Session expired → higgsfield auth login.

자세한 내용은 references/troubleshooting.md를 참조하세요.

참조 문서

필요시 로드:

references/model-catalog.md — 작업에 적합한 모델 선택
references/prompt-engineering.md — 효과적인 프롬프트 작성
references/media-inputs.md — 이미지/비디오 참조 흐름
references/troubleshooting.md — 일반적인 오류 및 해결 방법
references/marketing-avatars.md — 프리셋 vs 맞춤 아바타
references/marketing-products.md — URL 가져오기 vs 수동 제품 생성
references/marketing-setup-items.md — 훅/설정 발견 및 사용
references/marketing-modes.md — 모든 Marketing Studio 모드

Higgsfield 생성