2026/11/21

오늘의 이야기




post.mp4

19.52MB




힉스필드(Higgsfield)와 연동해서 AI 동영상 만드는 방법 정리


ai로 동영상 만들기



 


Higgsfield는 Seedance, Kling, Wan, MiniMax 같은 여러 영상·이미지 생성 모델을 한 곳에서 쓸 수 있는 서비스입니다. 이 글에서는 Claude 채팅에서 바로 영상을 만드는 방법(MCP)과 코드·자동화에서 API로 호출하는 방법을 정리했습니다. (작성 기준일: 2026-11-12, 공식 문서 기준)


결론부터



  • Claude와 연동해서 동영상 생성은 가능합니다.

  • 대화 중에 수동으로 만들 때는 MCP 커넥터, 블로그 자동화·앱 기능으로 넣을 때는 API가 맞습니다.

  • 두 방식은 결제 체계가 다릅니다. MCP는 구독 크레딧, API는 별도 계정의 선불 달러 잔액입니다.


방법 1. MCP 커넥터로 Claude에서 바로 생성


API 키 없이 Higgsfield 계정 인증만으로 연결됩니다. 활성화된 유료 Higgsfield 구독이 필요합니다.



  1. Claude(웹/데스크톱)에서 Settings → Connectors → Add custom connector로 이동

  2. MCP URL에 https://mcp.higgsfield.ai/mcp 입력 후 Connect

  3. 열리는 창에서 Higgsfield 계정으로 로그인해 권한 승인

  4. 새 대화에서 "내 Higgsfield 크레딧 잔액 알려줘"로 연결 확인


Claude Code를 쓴다면 터미널에서 한 줄로 추가할 수 있습니다.


claude mcp add higgsfield https://mcp.higgsfield.ai/mcp

주의: MCP로 생성하면 요금제와 관계없이 매번 크레딧이 차감됩니다.


방법 2. Higgsfield API로 코드에서 호출


API는 higgsfield.ai 구독과 별개의 API 계정을 쓰며, 선불 달러 잔액에서 생성할 때마다 차감됩니다. 최소 충전액은 $5이고, 영상은 출력 초당 요금으로 계산됩니다.


요청 흐름


API는 비동기 방식입니다. 요청을 큐에 넣고, 완료될 때까지 상태를 확인한 뒤 결과 URL을 받습니다.



  1. POST https://api.higgsfield.ai/{model_id}로 생성 요청 → request_id, status_url 반환

  2. GET https://api.higgsfield.ai/requests/{request_id}/status를 폴링

  3. 상태가 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. 글 본문에서 핵심 장면 1~2개를 뽑아 영상 프롬프트로 변환

  2. API로 영상 생성 후 폴링, 완료되면 mp4 저장

  3. 저장한 영상을 호스팅 후 글에 삽입하거나 썸네일·숏폼용으로 사용


n8n이나 Make를 쓴다면 HTTP Request 노드로 같은 API를 호출하는 방식으로 연결할 수 있습니다.


참고 링크






댓글 없음:

댓글 쓰기

오늘의 이야기

post.mp4 19.52MB 힉스필드(Higgsfield)와 연동해서 AI 동영상 만드는 방법 정리 ...