힉스필드(Higgsfield)와 연동해서 AI 동영상 만드는 방법 정리
Higgsfield는 Seedance, Kling, Wan, MiniMax 같은 여러 영상·이미지 생성 모델을 한 곳에서 쓸 수 있는 서비스입니다. 이 글에서는 Claude 채팅에서 바로 영상을 만드는 방법(MCP)과 코드·자동화에서 API로 호출하는 방법을 정리했습니다. (작성 기준일: 2026-11-12, 공식 문서 기준)
결론부터
- Claude와 연동해서 동영상 생성은 가능합니다.
- 대화 중에 수동으로 만들 때는 MCP 커넥터, 블로그 자동화·앱 기능으로 넣을 때는 API가 맞습니다.
- 두 방식은 결제 체계가 다릅니다. MCP는 구독 크레딧, API는 별도 계정의 선불 달러 잔액입니다.
방법 1. MCP 커넥터로 Claude에서 바로 생성
API 키 없이 Higgsfield 계정 인증만으로 연결됩니다. 활성화된 유료 Higgsfield 구독이 필요합니다.
- Claude(웹/데스크톱)에서 Settings → Connectors → Add custom connector로 이동
- MCP URL에
https://mcp.higgsfield.ai/mcp입력 후 Connect - 열리는 창에서 Higgsfield 계정으로 로그인해 권한 승인
- 새 대화에서 "내 Higgsfield 크레딧 잔액 알려줘"로 연결 확인
Claude Code를 쓴다면 터미널에서 한 줄로 추가할 수 있습니다.
claude mcp add higgsfield https://mcp.higgsfield.ai/mcp
주의: MCP로 생성하면 요금제와 관계없이 매번 크레딧이 차감됩니다.
방법 2. Higgsfield API로 코드에서 호출
API는 higgsfield.ai 구독과 별개의 API 계정을 쓰며, 선불 달러 잔액에서 생성할 때마다 차감됩니다. 최소 충전액은 $5이고, 영상은 출력 초당 요금으로 계산됩니다.
요청 흐름
API는 비동기 방식입니다. 요청을 큐에 넣고, 완료될 때까지 상태를 확인한 뒤 결과 URL을 받습니다.
POST https://api.higgsfield.ai/{model_id}로 생성 요청 →request_id,status_url반환GET https://api.higgsfield.ai/requests/{request_id}/status를 폴링- 상태가
completed가 되면 응답의video.url에서 영상 다운로드
인증 헤더는 Authorization: Key {API_KEY_ID}:{API_KEY_SECRET} 형식입니다. 키는 계정 잔액에 접근할 수 있으므로 서버 코드에서만 쓰고 소스 저장소에는 올리지 마세요.
상태 값
| status | 종료 여부 | 의미 |
|---|---|---|
| queued | 아니오 | 대기 중 (취소 가능) |
| in_progress | 아니오 | 생성 중 (취소 불가) |
| completed | 예 | 완료, 결과 URL 포함 |
| failed | 예 | 실패 (error 필드가 있을 수 있음) |
| nsfw | 예 | 콘텐츠 검수에서 거부됨 |
| canceled | 예 | 처리 전에 취소됨 |
Python 예제
아래 코드는 요청 제출 → 폴링 → 영상 저장까지의 뼈대입니다. 폴링 간격은 공식 문서 권장대로 약 2초에서 시작해 최대 10초까지 늘립니다. MODEL_ID와 PAYLOAD는 사용할 모델에 맞게 바꿔야 합니다. 모델마다 입력 파라미터가 다르므로 각 모델 문서(Models Gallery)에서 확인하세요.
import os, time, uuid, random
import requests
BASE = "https://api.higgsfield.ai"
KEY_ID = os.environ["HF_API_KEY_ID"]
KEY_SECRET = os.environ["HF_API_KEY_SECRET"]
HEADERS = {
"Authorization": f"Key {KEY_ID}:{KEY_SECRET}",
"Content-Type": "application/json",
}
# 모델별로 다름: 모델 문서에서 model_id와 입력 파라미터를 확인해 교체하세요
MODEL_ID = "your-vendor/your-video-model"
PAYLOAD = {
"prompt": "해 질 녘 해변을 걷는 고양이, 시네마틱",
# "image_url": "https://...", # 이미지→영상 모델이면 필요할 수 있음
}
def submit():
r = requests.post(
f"{BASE}/{MODEL_ID}",
headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
json=PAYLOAD,
timeout=30,
)
r.raise_for_status()
return r.json() # status, request_id, status_url, cancel_url
def wait(status_url, timeout_sec=600):
delay, start = 2.0, time.time()
while time.time() - start < timeout_sec:
r = requests.get(status_url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
if data["status"] in ("completed", "failed", "nsfw", "canceled"):
return data
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 1.5, 10)
raise TimeoutError("생성 대기 시간 초과")
def download(url, path):
with requests.get(url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(1 << 20):
f.write(chunk)
if __name__ == "__main__":
job = submit()
result = wait(job["status_url"])
if result["status"] == "completed":
download(result["video"]["url"], "output.mp4")
print("저장 완료: output.mp4")
else:
print("실패:", result["status"], result.get("error"))
Node.js 예제 (Node 18 이상)
import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";
const BASE = "https://api.higgsfield.ai";
const AUTH = `Key ${process.env.HF_API_KEY_ID}:${process.env.HF_API_KEY_SECRET}`;
// 모델별로 다름: 모델 문서에서 model_id와 입력 파라미터를 확인해 교체하세요
const MODEL_ID = "your-vendor/your-video-model";
const PAYLOAD = { prompt: "해 질 녘 해변을 걷는 고양이, 시네마틱" };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const TERMINAL = ["completed", "failed", "nsfw", "canceled"];
async function submit() {
const res = await fetch(`${BASE}/${MODEL_ID}`, {
method: "POST",
headers: {
Authorization: AUTH,
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify(PAYLOAD),
});
if (!res.ok) throw new Error(`submit ${res.status}: ${await res.text()}`);
return res.json();
}
async function wait(statusUrl, timeoutMs = 600_000) {
let delay = 2000;
const start = Date.now();
while (Date.now() - start < timeoutMs) {
const res = await fetch(statusUrl, { headers: { Authorization: AUTH } });
if (!res.ok) throw new Error(`status ${res.status}`);
const data = await res.json();
if (TERMINAL.includes(data.status)) return data;
await sleep(delay + Math.random() * 500);
delay = Math.min(delay * 1.5, 10_000);
}
throw new Error("생성 대기 시간 초과");
}
const job = await submit();
const result = await wait(job.status_url);
if (result.status === "completed") {
const video = await fetch(result.video.url);
await writeFile("output.mp4", Buffer.from(await video.arrayBuffer()));
console.log("저장 완료: output.mp4");
} else {
console.error("실패:", result.status, result.error);
}
비용 참고 (공식 블로그 기준, 변동 가능)
| 모델 | 영상 요금 |
|---|---|
| Kling 2.5 | 초당 $0.042 |
| Seedance 2.5 | 초당 $0.0738 |
| Kling 3.0 | 초당 $0.112 |
| DoP | 생성당 $0.125 |
모델과 가격은 자주 바뀌니 실제로 쓰기 전에 공식 가격표를 꼭 확인하세요.
운영 시 주의사항
- 결과물 보관 기간: 완료된 파일은 만료 시각(
expires_at) 이후 삭제되고 URL도 작동하지 않습니다. 응답 예시 기준 보관 기간은 7일이므로, 필요한 영상은 자체 저장소에 복사해 두세요. - 타임아웃 대응: 제출 응답을 못 받았다면 같은
Idempotency-Key로 재전송해 중복 과금을 피하세요. - 취소:
queued상태일 때만cancel_url로 취소할 수 있고, 생성이 시작되면 취소할 수 없습니다. - 약관: API 자체를 재판매하거나 독립 생성 서비스로 노출하는 것은 제한됩니다. 상업적 이용 범위는 약관을 확인하세요.
- 키 관리: API 키는 환경변수로만 주입하고, 앱(클라이언트)에 넣지 말고 서버에서 호출하세요.
블로그 자동화에 붙이는 아이디어
- 글 본문에서 핵심 장면 1~2개를 뽑아 영상 프롬프트로 변환
- API로 영상 생성 후 폴링, 완료되면 mp4 저장
- 저장한 영상을 호스팅 후 글에 삽입하거나 썸네일·숏폼용으로 사용
n8n이나 Make를 쓴다면 HTTP Request 노드로 같은 API를 호출하는 방식으로 연결할 수 있습니다.
댓글 없음:
댓글 쓰기