상품 사진 한 장으로 광고컷·세로 영상 뽑기

웹사이트와 뭐가 달라요?

내 상품이면 얼마 들까?

세팅 5단계

1. 콘솔 가입

   console.higgsfield.ai에서 가입해요. 모델 목록과 요금, 사용량 기록도 여기서 봐요.

2. API 잔액 충전

   웹사이트 구독 크레딧은 API에서 쓸 수 없어요. API 잔액을 따로 채워야 해요. 잔액이 0이 되면 자동으로 멈추고, 충전한 돈은 1년 뒤 소멸해요.

3. API 키 만들기

   키 ID와 시크릿은 만들 때 한 번만 보여요. 바로 비밀번호 관리자에 저장하세요. 키는 서버 쪽 코드에서만 쓰고, 깃허브 같은 곳에 올리지 마세요.

4. SDK 설치하고 키 넣기

   Python

   pip install higgsfield-client
   export HF_KEY="your-api-key-id:your-api-key-secret"

   복사
   TypeScript

   npm install @higgsfield/client
   export HF_CREDENTIALS="your-api-key-id:your-api-key-secret"

   복사

5. 첫 생성 해 보기

   공식 문서의 예제 그대로예요. 결과 이미지 주소가 출력되면 성공이에요.

   Python

   import higgsfield_client
   
   result = higgsfield_client.subscribe(
       "higgsfield-ai/soul/v2/standard",
       arguments={
           "prompt": "Editorial portrait in soft daylight",
       },
   )
   
   print(result["images"][0]["url"])

   복사
   TypeScript

   import { config, higgsfield } from "@higgsfield/client/v2";
   
   config({
     credentials: process.env.HF_CREDENTIALS,
   });
   
   const result = await higgsfield.subscribe(
     "higgsfield-ai/soul/v2/standard",
     {
       input: {
         prompt: "Editorial portrait in soft daylight",
       },
       withPolling: true,
     },
   );
   
   if (result.status === "completed") {
     console.log(result.images?.[0]?.url);
   }

   복사

상품 사진을 넣으려면

상품 사진을 바탕으로 만들려면 먼저 사진을 올리고, 받은 주소를 모델 입력에 넣어요.

1. 업로드 주소 받기

   올릴 파일 형식을 POST /files/generate-upload-url로 보내면 업로드 주소를 받아요. 주소 앞부분은 https://api.higgsfield.ai예요.

2. 그 주소로 파일 올리기

   받은 주소로 파일을 PUT 해요. 이때 Higgsfield 키는 함께 보내지 마세요. 업로드 주소는 1시간 뒤 만료돼요.

3. 받은 주소를 입력에 넣기

   응답의 public_url을 모델 입력(image_url 등)에 넣어요.

받는 형식: 이미지 JPEG·PNG·WebP·GIF, 영상 MP4, 오디오 WAV. SDK에는 upload_file·upload_image 같은 도우미도 있어요. 모델 ID와 입력 이름은 모델마다 달라요. 추측하지 말고 콘솔 모델 페이지의 코드 예시에서 복사하세요.

결과 받기

• 요청은 queued로 시작해 completed·failed·nsfw·canceled 중 하나로 끝나요. failed·nsfw는 과금되지 않고, 처리 시작 전에 취소하면 환불돼요.
• 결과 파일은 최소 7일 보관돼요. 끝나는 대로 바로 내려받으세요.
• 많이 돌릴 때는 상태를 계속 묻는 대신 웹훅으로 완료 알림을 받으면 편해요.
• 동시 요청 한도를 넘으면 400 에러(Maximum number of concurrent requests (N) has been reached)가 나요. 잠깐 기다렸다 다시 보내요.

상품 광고 프롬프트 3종

제가 쓰는 뼈대예요. {상품} 자리만 바꿔 넣으세요. 모델마다 결과가 다르니 한두 장 먼저 뽑아 보고 조절하세요.

Lifestyle product photo of {상품} placed on a wooden table by a sunny window, soft natural light, shallow depth of field, warm and clean mood, commercial photography, no text, no logo

Studio packshot of {상품}, centered on a seamless white background, softbox lighting, crisp soft shadow, high detail, e-commerce hero image, no text

Slow cinematic push-in on {상품}, a soft light sweep moving across the surface, subtle background bokeh, vertical 9:16 framing, premium commercial mood, no text

사진 속 사람 얼굴, 다른 회사 로고·상표가 들어가지 않게 하세요. 결과물의 상업 이용은 가능하지만, 들어간 요소의 권리는 따로 확인해야 해요.

코드 몰라도: AI 코딩 도구에 붙여넣을 프롬프트

Claude Code나 Codex 같은 AI 코딩 도구에 아래를 그대로 붙여넣으면, 상품 사진 폴더를 광고 이미지·세로 영상으로 바꿔 주는 작은 프로그램을 만들어 줘요.

내 컴퓨터에서 도는 작은 파이썬 프로그램을 만들어 줘.

목표: products/ 폴더에 있는 상품 사진마다 Higgsfield API로 광고 이미지 2장과 5초 세로 영상 1개를 만들어 output/<상품 이름>/ 폴더에 저장하기.

지켜 줄 것:
- 공식 Python SDK(pip install higgsfield-client)를 써. 키는 환경변수 HF_KEY("키ID:시크릿")에서만 읽고, 코드나 로그에 키를 절대 쓰지 마.
- 쓸 모델 ID와 입력 이름은 config.json에서 읽어(image_model, video_model, 사진을 넣는 입력 이름). 내가 콘솔 모델 페이지의 코드 예시에서 복사해 넣을게.
- 상품 사진은 공식 파일 업로드 방식으로 올리고, 받은 주소를 모델 입력에 넣어.
- 프롬프트는 prompts.json에서 읽고, {product} 자리에 파일 이름을 넣어.
- 요청마다 상태를 확인해서 completed면 바로 내려받아(결과는 7일 뒤 지워질 수 있어). failed·nsfw면 건너뛰고 기록만 남겨.
- 동시에 2개까지만 요청해. 동시 요청 한도 에러가 나면 잠깐 기다렸다 다시 보내.
- 끝나면 상품별 결과 파일 경로와 실패 목록을 요약해 줘.

먼저 폴더 구조와 config.json, prompts.json 예시를 보여 주고, 내가 확인하면 코드를 만들어 줘.

쓰기 전에 확인

• 웹사이트 구독 크레딧과 API 잔액은 따로예요.
• 키는 만들 때 한 번만 보여요. 환경변수로 쓰고 공개된 곳에 올리지 않아요.
• 결과 파일은 7일 안에 내려받아요.
• 충전금은 1년 뒤 소멸해요. 필요한 만큼만 채워요.
• API는 이미지·영상을 만드는 데까지예요. 쇼핑몰이나 SNS에 올리는 건 따로 연결해야 해요.
• 한국 결제 수단과 세금계산서 발행 여부는 공식 자료에서 찾지 못했어요. 결제 전에 콘솔에서 확인하세요.