Higgsfield API 가이드: 키 발급, 할인, OpenHiggsfield 연결, 첫 호출 코드

광고 · 이 글에는 제휴 링크가 포함되어 있으며, 링크를 통한 구매 시 수수료를 받습니다.

Higgsfield API 가이드: 키 발급부터 OpenHiggsfield 연결, 첫 호출까지

구독 없이 쓴 만큼만 내는 Higgsfield API의 키 발급과 충전, 할인 받는 순서, 힉스필드와 비슷한 화면의 OpenHiggsfield 연결법, curl과 SDK로 직접 호출하는 코드까지 한 문서에 정리했습니다.

구독 대신 API 키 하나로 힉스필드 모델을 씁니다

Higgsfield API는 힉스필드의 이미지·영상 모델을 API 키 하나로 부르는 개발자용 상품입니다. 월 구독이 아니라 지갑에 돈을 충전해 두고, 생성에 성공한 만큼만 빠져나갑니다. 공식 소개 페이지는 50개가 넘는 모델을 같은 방식으로 호출할 수 있다고 안내합니다. Seedance 2.5, Kling 3.0, MiniMax H3, 힉스필드 자체 모델인 Soul 2도 그 목록에 있습니다.

GitHub에는 힉스필드 스튜디오와 비슷한 화면을 코드로 만들어 둔 OpenHiggsfield가 올라와 있습니다. README에서는 스스로 오픈소스라고 소개합니다. 여기에 Higgsfield API 키를 넣으면 힉스필드에서 쓰던 모습 그대로 모델을 고르고 이미지와 영상을 뽑을 수 있습니다. 이 글은 성공지식백과 유튜브 영상에서 보여드린 흐름을 따라가면서, 영상에서 다루지 않은 호출 코드와 주의점까지 공식 문서 기준으로 채웠습니다.

TIP

가입은 아래 링크로 시작하세요

아래 링크로 Higgsfield API 콘솔에 가입하면 가입 할인과 모델 선택 할인, 비즈니스 이메일 인증 크레딧을 순서대로 받을 수 있습니다. 할인 조건은 이 글의 할인 받는 순서 섹션에 정리했습니다.

Higgsfield API 콘솔 열기

이 가이드에 담긴 것

API 키 발급과 충전
콘솔에서 키를 만들고 Billing에서 구독 크레딧과 별도로 충전하는 순서
할인 받는 순서
가입 15% 할인, 모델 선택 최대 50% 할인, 비즈니스 이메일 인증 15달러
OpenHiggsfield 연결
호스트 버전에 키를 넣어 바로 쓰는 법과 GitHub 저장소를 받아 직접 띄우는 법
코드로 직접 호출
인증 헤더, 요청과 응답, 상태 확인, 웹훅, 비용 미리 보기, SDK 예제
실제로 나온 비용
Soul 2 이미지 1장과 Seedance 2.5 15초 영상 청구액, fal.ai 가격 비교

시작 전 준비

Higgsfield API 잔액은 힉스필드 구독 크레딧과 따로 관리됩니다. 잔액 충전과 15달러 크레딧 모두 결제 카드 등록이 먼저입니다. OpenHiggsfield를 호스트 버전으로만 쓸 거라면 설치할 프로그램은 없고, 직접 띄우려면 Node.js와 pnpm이 필요합니다.

시작 전 확인

Higgsfield API 콘솔 계정
충전에 쓸 결제 카드
15달러 크레딧을 받으려면 인증 가능한 비즈니스 이메일
PC 브라우저 (콘솔과 스튜디오는 데스크톱 화면에서 쓰기 편합니다)
직접 배포할 경우에만 Node.js, pnpm, Git

0/5 완료

1단계: API 키 발급과 충전

키를 만드는 일과 돈을 채우는 일은 콘솔 안에서 따로 진행합니다. 힉스필드 구독으로 받은 크레딧은 API에서 쓸 수 없기 때문에, 구독 중이더라도 API용 잔액을 새로 채워야 합니다.

키 발급과 충전 순서

콘솔 접속

Higgsfield API 콘솔에 로그인합니다. 대시보드에서 키 발급 버튼을 찾습니다.

키 만들기

키 이름을 정해 키를 만들면 키 값이 표시됩니다. 아래 Copy Key 버튼으로 복사해 안전한 곳에 보관합니다. 키는 key ID와 secret 두 부분으로 이루어져 있고, 스튜디오나 SDK에는 id:secret 형태로 넣습니다.

카드 등록

왼쪽 메뉴의 Billing으로 들어가 하단의 Payment 추가 버튼으로 카드를 먼저 등록합니다.

비즈니스 이메일 인증

카드를 등록한 계정에서 비즈니스 이메일까지 인증하면 15달러가 잔액에 들어옵니다.

크레딧 충전

Add Credit 버튼을 누르고 충전할 금액을 골라 결제를 마칩니다.

주의

키는 비밀번호처럼 다룹니다

공식 문서는 API 키를 서버 쪽 코드에서만 쓰라고 안내합니다. 브라우저나 모바일 앱 코드에 넣으면 누구나 키를 꺼내 내 잔액으로 생성할 수 있습니다. 화면 녹화나 스크린샷에 키가 찍혔다면 콘솔에서 바로 새 키로 교체합니다.

할인 받는 순서: 가입 15%, 모델 선택 최대 50%

2026년 9월 17일 기준 공식 페이지에 안내된 출시 혜택은 네 가지입니다. 가입하면 15% 할인이 기본으로 붙고, 할인 모델을 직접 고르면 그 모델의 할인율이 최대 50%까지 올라갑니다. 비즈니스 이메일을 인증하고 카드를 등록하면 잔액에 15달러가 더해집니다.

혜택	조건	내용
가입 할인	콘솔 가입	15% 할인 (FAQ는 모든 모델, 상단 배너는 할인 대상 모델로 표기)
모델 선택 할인	콘솔에서 할인 모델 선택	고른 모델 최대 50% 할인
크레딧	비즈니스 이메일 인증과 카드 등록	잔액 15달러
동시 요청	첫 API 키	키당 동시 요청 20개부터 시작

영상을 녹화할 때 콘솔의 모델 선택 화면에서는 이미지 모델 1개와 영상 모델 2개를 고를 수 있었고, 고른 모델에 일주일 동안 50% 할인이 적용된다고 표시됐습니다. 영상에서는 영상 모델로 Seedance와 MiniMax H3, 이미지 모델로 Marketing Studio Image를 골랐습니다. 공식 소개 페이지 FAQ에는 모델 4개를 고른다고 적혀 있어 개수가 다르니, 가입 후 콘솔 화면에 표시된 개수와 기간을 기준으로 고르면 됩니다.

INFO

가격과 혜택은 자주 바뀝니다

위 표는 2026년 9월 17일에 공식 Higgsfield API 페이지에서 확인한 내용입니다. 모델별 현재 가격은 콘솔 카탈로그에 공개되어 있고, 결제 전 금액은 아래 비용 미리 보기 요청으로 확인할 수 있습니다.

2단계: OpenHiggsfield에 키 연결하기

OpenHiggsfield는 이미지와 영상을 한 입력창에서 만드는 웹 스튜디오입니다. GitHub README 기준으로 이미지 모델 8개, 영상 모델 30개를 합쳐 38개 모델이 카탈로그에 들어 있고, 모델마다 화면 비율·해상도·길이·오디오 같은 설정이 따로 표시됩니다. 스튜디오 자체는 무료이고, 생성 비용만 내 API 키의 잔액에서 빠집니다.

호스트 버전으로 바로 써보기

설치 없이 먼저 써보려면 이미 띄워 둔 호스트 버전을 씁니다. 영상에서도 이 화면에 키를 넣고 생성했습니다.

OpenHiggsfield 호스트 버전

설치 없이 브라우저에서 키를 넣고 바로 이미지와 영상을 만드는 스튜디오

www.openhiggsfield.ai

호스트 버전에 키 넣기

사이트 접속

위 카드의 호스트 버전 사이트에 들어갑니다.

키 추가

상단의 Add key 버튼을 누르고 1단계에서 복사한 키를 id:secret 형태로 붙여넣습니다.

저장

Save를 누르면 상단 표시등이 키가 등록된 상태로 바뀝니다. 키 없이 생성을 누르면 키 입력 창이 다시 열립니다.

INFO

호스트 버전에서 키가 보관되는 방식

README에 따르면 입력한 키는 서버 액션이 httpOnly 쿠키에 저장하고, 생성 요청은 브라우저가 아니라 서버 액션이 API로 보냅니다. 다른 사람에게 키가 공개되지는 않지만 키가 호스트 버전의 서버를 거쳐 갑니다. 이 점이 신경 쓰이거나 팀에서 쓸 거라면 아래 방법으로 직접 띄운 인스턴스를 쓰는 편이 안전합니다.

GitHub 저장소를 받아 직접 띄우기

저장소는 Next.js 16과 React 19로 만들어졌고 패키지 관리는 pnpm을 씁니다. 받아서 설치하고 개발 서버를 켜면 로컬에서 같은 스튜디오가 열립니다.

OpenHiggsfield GitHub 저장소

이미지·영상 38개 모델을 한 입력창에서 쓰는 스튜디오 코드

github.com

Terminal

$ git clone https://github.com/wide-trace/open-higgsfield.git
$ cd open-higgsfield
$ pnpm install
$ cp .env.example .env.local
$ pnpm dev
  http://localhost:3000

pnpm dev를 켜기 전에 복사한 .env.local에 값을 채웁니다. README에 적힌 환경 변수는 두 개입니다. HF_API_BASE_URL에는 생성 API 주소인 https://api.higgsfield.ai를 꼭 넣어야 합니다. 이 값이 비어 있으면 생성 요청이 에러로 끝납니다. OPEN_HIGGSFIELD_READ_WRITE_TOKEN은 Vercel Blob 토큰으로, 시작 이미지나 참조 영상처럼 파일을 올리는 기능에만 필요합니다. 값을 채운 뒤 브라우저에서 localhost:3000을 열고 Add key로 키를 넣습니다.

.env.local복사

HF_API_BASE_URL=https://api.higgsfield.ai
OPEN_HIGGSFIELD_READ_WRITE_TOKEN=

명령	하는 일
`pnpm dev`	3000번 포트로 개발 서버 실행
`pnpm build`	배포용 빌드
`pnpm start`	빌드 결과 실행
`pnpm brand`	아이콘과 OG 카드 다시 생성

주의

코드를 고쳐 배포하기 전에 라이선스를 확인하세요

2026년 9월 17일 확인 시점에 저장소에는 라이선스 파일이 없고 README에도 라이선스 조항이 없습니다. 라이선스가 없으면 기본 저작권이 적용돼, 저작자의 허락 없이 코드를 복제·수정·배포할 수 없습니다. 코드를 고쳐 서비스로 내려면 저작자에게 허락을 받거나 라이선스가 추가됐는지 먼저 확인합니다.

저장소가 업데이트되면 변수 이름이나 필요한 값이 바뀔 수 있으니 README와 .env.example을 함께 확인합니다.

3단계: 이미지와 영상 만들어 보기

키를 넣었으면 모델을 고르고 설정을 맞춘 뒤 프롬프트를 넣습니다. 모델 선택 창, 설정 칸, 결과 갤러리 배치가 힉스필드 화면과 비슷해서 힉스필드를 써 본 사람이라면 따로 익힐 것이 거의 없습니다. 아래는 영상에서 실제로 넣은 설정입니다.

Soul 2로 광고 모델 이미지

Soul 2는 힉스필드의 이미지 생성 모델로, 인물과 캐릭터 이미지에 강합니다. 영상에서는 화면 비율 16:9, 해상도 1080으로 맞추고 아래 문장을 넣었습니다. 결과는 여름 음료를 든 한국인 모델 이미지였고, 콘솔 사용 내역에 찍힌 비용은 0.01달러였습니다.

Soul 2 프롬프트 (16:9, 1080)

상큼한 여름 음료 광고에 어울리는 한국인 모델

Seedance 2.5로 15초 영상

영상은 Seedance 2.5를 골라 화면 비율 16:9, 해상도 720, 오디오 켜기, 길이 15초로 만들었습니다. 영상 녹화 시점 기준 이 스튜디오에서 Seedance 2.5는 720까지 선택할 수 있었습니다. 대규모 전투 장면을 보려고 진영마다 병사 수를 적어 넣었습니다.

Seedance 2.5 프롬프트 (16:9, 720, 오디오, 15초)

머리와 몸이 2등신인 픽셀 캐릭터들, 두 개의 진영이 서로 전쟁하는 장면. 기마병, 궁수, 창병, 마법사. 각 진영당 50명 이상의 병사들.

생성이 끝나면 결과를 눌러 재생합니다. 실패하거나 NSFW로 걸린 요청은 스튜디오 갤러리에 실패 타일로 남고, 같은 프롬프트와 모델로 다시 시도할 수 있습니다.

코드로 직접 호출하기

내 서비스에 생성 기능을 붙이려면 스튜디오 대신 API를 직접 호출합니다. 공식 문서 기준으로 흐름은 세 단계입니다. 모델 엔드포인트에 요청을 보내면 곧바로 request_id와 상태 확인 주소가 돌아오고, 그 주소를 확인하다가 완료되면 결과 파일 URL을 받습니다.

인증 헤더

모든 요청에는 Authorization 헤더에 Key 뒤로 key ID와 secret을 콜론으로 이어 붙여 보냅니다. Bearer 토큰 형식이 아니라는 점에 주의합니다. 요청은 모두 api.higgsfield.ai 주소로 보냅니다.

env.sh복사

export HF_API_KEY_ID="your-api-key-id"
export HF_API_KEY_SECRET="your-api-key-secret"

# 모든 요청에 붙는 헤더
# Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}

이미지 생성 요청과 응답

아래는 공식 Quickstart의 Soul 2 요청입니다. 생성은 비동기라서 응답에 이미지가 바로 들어 있지 않고, 대기열에 들어갔다는 상태가 먼저 옵니다.

soul-request.sh복사

curl --request POST \
  --url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"prompt": "A quiet alpine lake at sunrise, editorial photography"}'

response.json복사

{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}

영상도 같은 방식입니다. Seedance 2.5 텍스트 투 비디오 엔드포인트는 bytedance/seedance-2.5/text-to-video이고, 공식 문서 기준 해상도는 480p와 720p를 받습니다.

seedance-request.sh복사

curl --request POST \
  --url https://api.higgsfield.ai/bytedance/seedance-2.5/text-to-video \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"prompt": "A cinematic tracking shot of a cyclist along a sunlit coastal road", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9"}'

상태 확인과 웹훅

응답의 status_url을 주기적으로 확인하다가 상태가 completed, failed, nsfw, canceled 중 하나가 되면 멈춥니다. 공식 문서는 2초 간격으로 시작해 최대 10초까지 간격을 늘리라고 권합니다. 완료된 이미지 요청은 images 배열에, 영상 요청은 video 객체에 파일 URL이 들어 있습니다.

status.sh복사

curl --url "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"

계속 확인하는 대신 완료 알림을 받으려면 요청 주소에 hf_webhook 쿼리 파라미터로 내 서버 주소를 붙입니다. 요청이 completed, failed, nsfw 상태가 되면 그 주소로 POST가 옵니다. 받는 쪽은 공개된 HTTPS 주소여야 하고 10초 안에 응답해야 합니다. 같은 알림이 여러 번 올 수 있으니 request_id와 상태로 중복을 거릅니다.

webhook-request.sh복사

curl --request POST \
  --url "https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard?hf_webhook=https%3A%2F%2Fexample.com%2Fwebhooks%2Fhiggsfield" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"prompt": "Editorial portrait in soft daylight"}'

비용 미리 보기

생성하기 전에 같은 파라미터로 estimate 엔드포인트를 부르면 크레딧과 달러 금액이 돌아옵니다. 설정에 따라 가격이 크게 달라지는 영상 모델은 이 요청으로 먼저 확인하는 습관이 좋습니다.

estimate.sh복사

curl --request POST \
  --url https://api.higgsfield.ai/estimate/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"prompt": "Editorial portrait in soft daylight"}'

SDK로 호출하기

공식 SDK는 Python과 TypeScript 두 가지입니다. 둘 다 인증, 요청, 상태 확인을 대신 처리하고, 서버 쪽 환경에서만 쓰도록 만들어져 있습니다. 키는 id:secret 형태의 환경 변수 하나로 넣습니다.

PythonTypeScript

python

# pip install higgsfield-client
# export HF_KEY="your-api-key-id:your-api-key-secret"
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

// npm install @higgsfield/client
// export HF_CREDENTIALS="your-api-key-id:your-api-key-secret"
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.isCompleted) {
  console.log(result.jobs[0].results?.raw.url);
}

실제로 나온 비용과 가격 비교

영상에서 만든 두 결과물의 비용과, 같은 조건의 다른 플랫폼 가격을 나란히 정리했습니다. 콘솔 카탈로그에 표시되는 가격은 모델의 시작 가격이고, 해상도·오디오·길이에 따라 실제 청구액이 달라집니다.

항목	조건	금액	출처
Soul 2 이미지	16:9, 1080, 1장	0.01달러	영상 속 콘솔 사용 내역
Seedance 2.5 영상	16:9, 720, 오디오, 15초	5.89달러	영상 속 콘솔 사용 내역
fal.ai Seedance 2.5	720p, 초당	약 0.473달러 (15초면 약 7.1달러)	fal.ai 모델 가격 안내
Seedance 2.5 카탈로그 가격	초당 시작 가격	0.144달러 (정가 0.2057달러)	Higgsfield API 공식 페이지
Soul 2 카탈로그 가격	이미지당 시작 가격	0.0032달러	Higgsfield API 공식 페이지

같은 720p 오디오 15초 영상을 기준으로 보면 Higgsfield API 쪽이 1달러 남짓 적게 나왔습니다. 이미지는 한 장에 1센트 수준이라, 이미지 위주로 쓰면서 구독 크레딧을 다 쓰지 못하고 넘기던 사람은 필요한 달에만 충전하는 방식이 부담이 적습니다. 영상에서는 이미지 위주의 라이트 유저라면 50달러에서 100달러 정도를 넉넉히 충전해 두면 크레딧이 모자랄 일이 거의 없다고 소개했습니다. 충전한 크레딧은 잔액에 들어온 날부터 1년 뒤 만료되니 충전 금액은 그 기간을 감안해 정합니다.

TIP

실패한 요청은 과금되지 않습니다

공식 문서 기준으로 failed나 nsfw로 끝난 요청은 청구되지 않고, 요청을 받을 때 잡아 둔 크레딧은 자동으로 돌려받습니다. 대기열에 있는 동안 취소한 요청도 환불됩니다. 생성이 시작된 요청은 취소할 수 없습니다.

구독 플랜과 API, 어느 쪽이 맞을까

API가 생겼다고 구독이 필요 없어지지는 않습니다. 힉스필드 웹사이트의 다양한 기능을 화면에서 편하게 쓰는 사람에게는 플러스, 울트라 같은 구독 플랜이 여전히 맞고, 쓴 만큼만 내고 싶거나 내 서비스에 생성 기능을 붙이려는 사람에게는 API가 맞습니다.

이런 경우	맞는 쪽
이미지 위주로 가끔 만들어서 구독 크레딧이 남는다	API 충전
내 앱이나 사내 도구에 생성 기능을 붙이고 싶다	API
직접 띄운 OpenHiggsfield를 팀원이 각자 키로 쓰고 싶다	API
힉스필드 웹사이트의 스튜디오·앱 기능을 매일 화면에서 쓴다	구독 플랜

자주 막히는 문제와 FAQ

키 발급부터 첫 호출까지 막히기 쉬운 부분을 공식 문서 기준으로 모았습니다.

힉스필드 구독 크레딧으로 API를 쓸 수 있나요?

쓸 수 없습니다. API는 콘솔의 Billing에서 따로 충전한 잔액으로 과금됩니다. 구독 중이어도 API용 잔액을 채워야 합니다.

401 Unauthorized가 나옵니다.

키가 없거나, 형식이 틀리거나, 폐기·오타로 유효하지 않은 경우입니다. Authorization 헤더가 Key key_id:secret 형식인지, Bearer로 보내지 않았는지 확인합니다. 스튜디오에는 id:secret을 콜론으로 이어 한 줄로 넣습니다.

생성 요청이 400으로 거절됩니다.

동시 요청 한도에 걸렸을 수 있습니다. 공식 문서는 한도에 도달하면 400 Bad Request와 함께 최대 동시 요청 수를 알려주는 메시지가 온다고 안내합니다. 진행 중인 요청이 끝난 뒤 다시 보내고, 한도는 콘솔에서 확인합니다. 공식 페이지 기준 첫 키는 동시 요청 20개부터 시작합니다.

만든 결과 파일은 얼마나 보관되나요?

생성 후 최소 7일 동안 접근할 수 있고 그 뒤에는 삭제될 수 있습니다. 계속 쓸 파일은 내려받아 내 저장소에 옮겨 둡니다.

키가 노출됐으면 어떻게 하나요?

콘솔에서 해당 키를 폐기하고 새 키를 만듭니다. 공식 문서는 키를 URL, 로그, 스크린샷에 남기지 말고 개발용과 운영용 키를 나눠 쓰라고 권합니다.

OpenHiggsfield를 고쳐서 내 서비스로 내도 되나요?

fal이나 Replicate에서 옮기려면 코드를 많이 바꿔야 하나요?

공식 페이지는 요청 보내기, 상태 확인, 결과 받기라는 흐름이 같아서 대부분 환경 변수의 키를 바꾸는 것으로 옮긴다고 안내합니다. 다만 모델 엔드포인트와 파라미터 이름은 플랫폼마다 다를 수 있으니 콘솔의 모델별 문서를 확인합니다.