목록 · 가이드

힉스필드 API 사용법, 키 발급부터 첫 이미지까지

도도리가 직접 확인하고 정리했습니다 · 2026-09-29 기준으로 확인

코드 없이 클로드에서 말로 쓰려면 이쪽입니다. 힉스필드 MCP 설치와 연결 방법

힉스필드 API는 힉스필드의 이미지·영상 모델을 내 프로그램 안에서 부르는 통로입니다. 2026년 9월 16일에 나왔고, 키 하나로 50개가 넘는 모델을 부를 수 있다고 힉스필드가 밝혔습니다. 이미 있던 힉스필드 MCP가 "클로드에게 말로 부탁하는" 길이라면, API는 "코드가 주문서를 바로 넣는" 길입니다. 이 글은 키 받기부터 첫 이미지, 요금 계산, 그리고 MCP와 무엇이 다른지까지 순서대로 짚습니다.

한 장으로 먼저: MCP와 API

식당에 빗대면 쉽습니다. MCP는 종업원(클로드)에게 "매운 거 하나요" 하고 말로 주문하는 방식입니다. API는 주방 주문 단말기에 메뉴 번호와 수량을 직접 찍어 넣는 방식입니다. 음식을 만드는 주방(힉스필드 모델)은 같지만, 주문하는 사람과 계산서가 다릅니다.

힉스필드 고객센터도 두 상품을 이렇게 가릅니다. API는 "내 제품 안에 생성 기능을 넣을 때", MCP와 CLI는 "AI 에이전트로 생성할 때" 씁니다. 청구서도 둘입니다. higgsfield.ai 구독이 있어도 API 사용료는 따로 나가고, 반대로 API만 쓰려고 구독할 필요는 없습니다.

나는 어느 쪽인가요

세 줄 이상 고개가 끄덕여지는 쪽을 고르시면 됩니다.

둘 다 쓰는 방법도 있습니다. MCP로 클로드와 이야기하며 마음에 드는 문장과 모델을 찾고, 그 문장을 API 코드에 넣어 100장을 돌리는 식입니다. 시안은 대화로, 반복은 코드로 나누면 크레딧과 시간이 둘 다 덜 듭니다.

키를 받는 순서

힉스필드 API 안내 페이지에서 시작합니다. higgsfield.ai 구독 계정과 다른 API 전용 계정을 만듭니다. 고객센터는 이 콘솔을 "Open Higgsfield" 라고 부르고, 기술 문서에는 예전 이름인 "Higgsfield Cloud" 가 남아 있습니다. 같은 곳입니다.

첫 이미지 3분 코스

공식 빠른 시작 문서의 예제 그대로입니다. 힉스필드 자체 모델인 소울 2(Soul 2)로 사진 한 장을 주문합니다. 먼저 터미널입니다.

export HF_API_KEY_ID="발급받은-키-ID"
export HF_API_KEY_SECRET="발급받은-비밀값"

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" }'

이 명령은 사진을 바로 돌려주지 않습니다. 돌아오는 것은 접수증입니다. status 가 queued(대기)이고, 주문 번호인 request_id와 상태를 볼 주소 status_url이 들어 있습니다. 이미지와 영상은 몇 초에서 몇 분이 걸리기 때문입니다.

파이썬이면 기다리는 일까지 라이브러리가 맡습니다. pip install higgsfield-client로 깔고(파이썬 3.8 이상), 키는 HF_KEY="키ID:비밀값" 한 줄로 환경변수에 넣습니다.

import higgsfield_client

result = higgsfield_client.subscribe(
    "higgsfield-ai/soul/v2/standard",
    arguments={
        "prompt": "Editorial portrait in soft daylight",
    },
)

print(result["images"][0]["url"])

subscribe는 주문을 넣고, 끝날 때까지 상태를 물어보고, 결과를 돌려주는 일을 한 번에 합니다. 마지막 줄에 찍히는 주소가 완성된 사진입니다. 자바스크립트(타입스크립트)용은 npm install @higgsfield/client이고, 이쪽은 키를 HF_CREDENTIALS라는 이름으로 읽습니다. 도구마다 환경변수 이름이 달라 처음에 가장 많이 헷갈리는 자리입니다.

주문하고 기다리는 구조

API가 일하는 방식은 음식 배달 앱과 같습니다. 주문하면 주문 번호가 나오고, "조리 중" 을 몇 번 거쳐 "배달 완료" 가 됩니다.

상태를 물어볼 때는 처음 2초 간격으로 시작해 10초까지 늘리라고 문서가 권합니다. 1초마다 계속 두드리면 서버에도 내 코드에도 좋을 것이 없습니다. 기다리기 싫다면 웹훅을 씁니다. 주문 주소 끝에 ?hf_webhook=내-서버-주소를 붙이면, 끝났을 때 힉스필드가 내 서버로 결과를 보내 줍니다. 내 서버는 10초 안에 답해야 하고, 같은 알림이 두 번 올 수도 있으니 주문 번호로 중복을 거르십시오.

내 사진을 넣어 영상을 만드는 모델이라면, 공개된 https 주소를 그대로 넣거나 업로드 주소를 먼저 받아(POST /files/generate-upload-url) 파일을 올립니다. 업로드 주소는 1시간 뒤 만료됩니다. jpeg·png·webp·gif·wav·mp4를 받습니다.

요금 계산기

API는 구독이 아니라 충전식입니다. 이미지는 장당, 영상은 초당 값이 붙고, 잔액이 모자라면 주문이 막힙니다(마이너스로 가지 않습니다). 실패했거나 정책 위반으로 막힌 주문은 돈을 받지 않고 자동으로 돌려줍니다. 아래는 출시 공지에 나온 시작가로 계산한 값입니다.

숫자로 보면 감이 옵니다. 공지에 나온 예시대로 클링 3.0으로 10초 영상 한 편이면 1.12달러입니다. 소울 2 사진 100장은 0.32달러입니다. 반대로 시댄스 2.0 영상은 공지 기준 초당 0.9332달러라, 10초 한 편이 9달러를 넘습니다. 모델 하나 바꾸는 것으로 값이 몇십 배 달라지니, 시험할 때는 싼 모델과 짧은 길이로 먼저 돌리십시오.

MCP와 뭐가 다른가

이제 처음 질문으로 돌아옵니다. 한 줄로 줄이면 MCP는 대화로 한 장씩, API는 코드로 여러 장씩입니다. 조금 더 풀면 다섯 가지가 다릅니다.

출처: 힉스필드 고객센터 "API란 무엇인가"(2026-09-16), 힉스필드 MCP 안내. 힉스필드 사이트의 무제한·무료 생성 혜택은 사이트 안에서만 적용되고, MCP로 부르면 늘 크레딧이 빠진다고 고객센터가 밝혔습니다.

고를 수 있는 모델도 조금 다릅니다. 힉스필드는 API의 모델 목록이 사이트와 다를 수 있다고 밝혔습니다. 공식 API 문서에서 확인되는 것은 소울 2, 소울 시네마, 시댄스, 클링, 완(Wan), 레크래프트, 그록 이미지 등입니다. 사이트와 MCP에서 보이는 비오(Veo), 소라(Sora), 나노 바나나는 9월 29일 현재 공식 API 문서에서는 확인하지 못했습니다. 이 모델이 꼭 필요하시다면 콘솔의 모델 목록을 먼저 보십시오.

한꺼번에 돌릴 수 있는 양에도 한도가 있습니다. 출시 공지는 새 키로 동시에 20건을 돌릴 수 있다고 했고, 기술 문서의 예시는 4건이며 계정과 모델에 따라 다르다고 적었습니다. 한도를 넘으면 "Maximum number of concurrent requests" 오류가 납니다. 몇 백 장을 돌릴 때는 한 번에 몇 건씩 나눠 보내십시오.

MCP 쪽을 처음 붙이신다면 힉스필드 MCP로 영상·이미지 만드는 법과 힉스필드 MCP 설치와 연결 방법을 보십시오. 이 사이트의 가이드 그림 가운데 여럿이 MCP로 만든 것입니다.

실전: 상품 사진 다섯 장을 한 번에

쇼핑몰 상품 설명 다섯 줄을 넣으면 사진 다섯 장의 주소가 나오는 가장 단순한 반복입니다. 위의 공식 예제를 반복문에 넣은 것뿐입니다.

import higgsfield_client

items = [
    "white ceramic mug on a wooden table, morning light",
    "linen tote bag hanging on a door, soft shadow",
    "glass perfume bottle on marble, studio lighting",
    "wool scarf folded on a chair, cozy winter mood",
    "leather notebook with a pen, top view, minimal",
]

for text in items:
    result = higgsfield_client.subscribe(
        "higgsfield-ai/soul/v2/standard",
        arguments={"prompt": text},
    )
    print(text, "→", result["images"][0]["url"])

이 코드는 한 장이 끝나야 다음 장을 주문합니다. 느리지만 동시 한도에 걸리지 않고, 비용이 한 장씩 쌓이는 것을 눈으로 볼 수 있어 처음에 안전합니다. 결과 주소는 7일이 지나면 사라질 수 있으니, 받자마자 내 저장소로 옮기는 줄을 덧붙이십시오.

자주 묻는 질문

이어서 보기