MiniMax H3 LoRA API 가이드: 모드 선택과 가중치 검증

직접 만든 LoRA는 필요한 샷을 통과할 때만 불러 쓸 가치가 있습니다. 캐릭터, 동작, 소리가 함께 맞아야 합니다. SpicyAPI의 MiniMax H3 LoRA(spicyapi.ai)는 오픈 웨이트 H3 영상 모델에 loras 필드가 있습니다. 요청 하나에 직접 만든 .safetensors 파일을 최대 3개까지 넣을 수 있고, 각각의 강도는 0에서 4 사이입니다.

시작 지점에 따라 작업을 고르고, H3용으로 학습된 파일을 직접 연결하세요. 스타일 LoRA는 scale 1에서, 컨셉 LoRA는 0.6에서 0.8 사이에서 시작하고, 3초 480p 드래프트($0.15)를 loras가 비어 있는 같은 요청과 비교해 판단하세요. 2026년 9월 테스트 기준으로 세 작업 모두 성인 요청을 전달했으며, SpicyAPI는 불러온 가중치에 추가 콘텐츠 필터를 붙이지 않습니다.

시작 지점에 따라 작업 고르기

세 작업 모두 480p, 540p, 768p, 1080p 중 하나로, 같은 패스에서 스테레오 소리와 함께 3~15초짜리 MP4를 돌려줍니다. LoRA를 불러오는 데 추가 비용은 없습니다. 넣을 LoRA가 없다면 기본 H3가 더 저렴합니다. 영상 초에 돈을 쓰기 전에 캐릭터나 화면을 정해 놓고 싶다면 H3 Image LoRA로 먼저 스틸 이미지를 만드세요. 같은 loras 배열을 그대로 이어서 쓸 수 있습니다(스틸과 영상 비교).

H3에 맞는 LoRA 고르기

파일은 MiniMax H3용으로 학습되어 있어야 합니다. 다른 베이스 모델용 LoRA는 호환되지 않으며, H3 어댑터도 로더가 지원하는 작업과 가중치 레이아웃이 필요합니다. H3 LoRA는 최신이라 품질 편차가 크니, 베이스와 트리거 단어, 동작하는 강도를 밝힌 모델 카드를 찾으세요. 아래 두 파일은 그것을 갖추었고 이 API에서 로드됩니다.

둘 다 H3 Community License를 사용하며, 사용 지역과 용도에 제한이 있습니다. 상업 작업 전에 반드시 읽으세요.

모델 카드에서는 트리거와 강도만 가져오세요. 로컬 ComfyUI나 다른 호스트를 위해 쓰인 레시피에는 이 작업에 없는 제어 항목(prompt_expansion_mode, 스텝 수, 샘플러, weight_name, 링크 대신 리포지토리 이름)이 들어 있고, 속도 증류(Turbo) LoRA는 로컬 샘플링 스텝을 줄이려고 만들어졌으니 건너뛰세요.

파일 연결하기

path는 로그인 없이 .safetensors 파일을 그대로 돌려주는 직접 HTTPS 링크여야 합니다. Hugging Face에서는 주소창에 보이는 /blob/ 페이지가 아니라 /resolve/ 링크입니다. 요청에 자격 증명 필드가 없으므로, 비공개 파일은 작업이 끝날 때까지 유효한 사전 서명 링크가 필요합니다. main 대신 커밋 해시를 넣으면 다음 달에도 같은 요청이 같은 파일을 불러옵니다. /blob/ 페이지, 없는 파일, 비공개 리포지토리는 작업이 만들어지기 전에 400으로 거부됩니다. 작업이 접수된 뒤 실패했다면 같은 요청을 "loras": []로 다시 보내세요. 그 요청이 성공하면 문제가 파일 쪽(접근, 호환성, 효과)이고, 그것도 실패하면 프롬프트나 입력을 보세요.

먼저 Playground에서 해보세요

1. 텍스트→영상 페이지를 열고 Playground 탭의 Form 뷰에 머무르세요. 실행하려면 잔액이 있는 계정으로 로그인합니다. 이미지→영상과 레퍼런스→영상은 각자 페이지가 있습니다(위 표의 링크).
2. Prompt에 트리거 단어를 먼저 쓰고, 그다음 샷을 짧은 타임라인으로 쓰세요(누가 나오고, 무엇을 하고, 카메라가 어떻게 움직이는지). 소리는 별도의 Audio: 줄에 두세요. LoRA가 이미 하는 것을 길게 설명하면 가중치와 서로 부딪히는 경향이 있습니다.
3. Style LoRAs 아래에서 LoRA file에 직접 파일 링크를 붙이고 Strength를 정하세요. Add item으로 최대 세 개의 파일을 넣을 수 있습니다.
4. Resolution에서 480p, Duration에서 3을 골라 저렴하게 첫눈을 보고, Seed를 정한 뒤 실행하세요.
5. Remove item를 누르고 같은 프롬프트와 seed로 다시 실행해 두 클립을 비교하세요. 비슷해 보이면 그 LoRA는 아무 일도 하지 않은 것입니다(아래 실패 표 참고).

Form 뷰의 MiniMax H3 텍스트→영상 Playground. Prompt 필드와 Run 버튼이 보입니다. LoRA 페이지는 같은 폼에 Style LoRAs 구역을 더합니다.

Playground의 요청 본문은 API가 받는 것과 같은 JSON이라, 여기서 동작한 설정은 코드로 그대로 옮길 수 있습니다. 나머지 두 작업은 각자 입력을 더합니다:

• 이미지→영상은 Input image(여는 프레임)와 선택 사항인 Closing frame을 더합니다. 새 장면이 아니라 그 프레임 안에서 다음에 무슨 일이 일어나는지 쓰세요. 컨셉 LoRA를 1로 두고 피사체를 다른 방으로 옮겨 달라는 프롬프트를 넣으면 여는 프레임이 대체됐지만, 같은 프레임 안의 동작을 서술하면 프레임이 유지됐습니다. 화면 비율 필드가 없으니 먼저 원하는 모양으로 프레임을 잘라내고 움직일 여유를 남기세요.
• 레퍼런스→영상은 Reference images(9개까지), Reference videos(3개까지), Reference audio(3개까지)를 더합니다. 프롬프트를 입력마다 짧은 문장 하나로 시작하고 각각에 한 가지 역할만 맡기세요. Picture 1은 그 여성, Picture 2는 그 방, Video 1은 카메라 이동, Audio 1은 그녀의 목소리입니다. 클립에서 동작을 빌릴 때는 사람은 이미지에서 왔고 동작만 클립에서 왔음을 분명히 말하세요. 그 문장이 없으면 클립에 있던 댄서까지 따라옵니다. 좋은 스틸 이미지 세 장이 겹치는 아홉 장보다 정체성을 더 잘 지킵니다.

각 모델 페이지의 Playground는 준비된 예시로 열리고, Request body 패널에 정확한 JSON이 나옵니다. 그 예시를 세 번 실행한 결과입니다:

레퍼런스 클립은 결과 길이에 더해 클립의 초 단위로 과금되며, 클립은 총 15초까지입니다. 짧게 유지하세요.

그다음 코드로 실행하기

Python SDK(pip install spicyapi)를 설치하고, 서버 환경에 SPICY_API_KEY를 설정한 뒤 아래 텍스트→영상 요청을 실행하세요. 다른 작업은 이미지→영상이면 model을 바꾸고 aspect_ratio를 빼고 image_url을 넣고, 레퍼런스→영상이면 model을 바꾸고 reference_image_urls를 넣으세요(aspect_ratio는 그대로 둡니다).

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="minimax/h3-lora/text-to-video",
    input_data={
        "prompt": "vh5tape, worn VHS tape with light tracking noise. A woman in a red satin dress sits alone in a late-night diner booth, turns toward the camera and slowly smiles, neon light flickering in the rain-streaked window behind her. Slow push-in. Audio: rain on glass, a jukebox ballad muffled through the tape, quiet room hum.",
        "aspect_ratio": "4:3",
        "resolution": "480p",
        "duration_seconds": 5,
        "seed": 42,
        "loras": [{
            "path": "https://huggingface.co/KennethFal/vh5tape-vhs-lora-minimax-h3/resolve/d25a4ab75aba899aa508220321525c8465ac11af/vh5tape.safetensors",
            "scale": 1.0,
        }],
    },
    idempotency_key=str(uuid.uuid4()),
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"])  # copy the video to your own storage now

생성, 대기, 다운로드, 재시도, 오류 코드는 tasks 가이드와 Python SDK 레퍼런스에 다룹니다. 생성된 파일은 최대 14일 보관되므로, 반환된 링크에 뭔가를 얹기 전에 보관과 전달을 확인하세요. 운영 환경에서는 폴링과 웹훅을 비교한 글(현재 영어로만 제공되는 async-task-api-polling-vs-webhook)이 선택에 도움이 됩니다.

또는 Agent에게 맡기기

어시스턴트가 생성 작업을 실행해야 할 때, 세 가지 공식 도구는 모두 가격을 보여 주고 유료 호출 전에 확인을 요청합니다.

• CLI. 같은 input 객체를 t2v.json에 넣고, 그다음 실행하세요:

``bash spicyapi tasks create --model minimax/h3-lora/text-to-video --input-file t2v.json --wait ``

CLI 문서를 보세요. npx @spicyapi/cli는 설치 없이 동작합니다.

• MCP server. 어시스턴트에 MCP server를 추가한 뒤 이렇게 물어보세요: "Run MiniMax H3 LoRA text-to-video with this prompt and this weights link at strength 1, 480p, 3 seconds." spicyapi_task_create를 호출해 가격 확인에서 멈추고, 이어서 spicyapi_task_wait를 호출합니다.
• Skill. npx skills add spicyapi-ai/spicy-skill는 Agent Skill을 설치합니다. 이를 통해 코딩 어시스턴트가 필드를 추측하는 대신 실제 모델 스키마를 읽습니다.

강도 설정하기

scale은 0에서 4까지며 1이 중립입니다. 스타일 LoRA는 1, 컨셉 LoRA는 0.6~0.8에서 시작하세요. 그다음 사다리를 돌리면 됩니다. 같은 프롬프트와 seed로 480p, 3초에서 scale 0.5, 0.8, 1.1을 실행하고, loras가 비어 있는 실행을 하나 더 돌립니다. 한 번에 하나만 바꾸세요. 고정된 seed는 실행을 비교 가능하게 만들 뿐 같게 만들지는 않으므로, 픽셀이 아니라 화면과 동작을 판단하세요.

읽기에 맞는 단계를 남기거나, 두 단계를 중간으로 잡으세요. 피사체, 동작, 소리가 무너지기 시작하면 강도를 더 올리지 마세요. 기준선부터가 그 샷을 못 만든다면 어떤 scale로도 고쳐지지 않습니다. 첫 프레임이 아니라 클립 전체를 보고 들으세요. LoRA가 소리까지 바꿀 수 있기 때문입니다(vh5tape는 일부러 둔하게 만듭니다). vh5tape 카드에는 가벼운, 중간, 강한 마모의 프롬프트 구절도 적혀 있으니, scale을 1보다 올리기 전에 그 구절을 바꾸세요.

세 개까지 쌓기

결합하기 전에 각 파일을 따로 시험하세요. 광택 있는 인물 사진으로 학습한 캐릭터 LoRA는 강한 테이프 룩과 부딪힐 수 있고, 동작 LoRA는 피사체를 구도에서 벗어나게 돌릴 수 있습니다. 쌓은 것이 어긋나면 seed와 프롬프트를 고정한 채 항목을 하나씩 빼보세요. 다시 정상으로 돌아왔다면 그 어댑터, 또는 남은 묶음과의 상호작용이 원인입니다. 가장 강한 가중치부터 낮추세요. 둘이 충돌할 때 어느 요구가 이기는지(예를 들어 질감보다 정체성)를 미리 정해 두고, 텍스트에서 동작했던 묶음은 사진 프레임이나 레퍼런스에 쓰기 전에 다시 시험하세요.

비용은 얼마인가

• 480p에서 3초: $0.15. 480p에서 5초: $0.25. 1080p에서 5초: $1.00.
• 위 세 요청은 $0.25·$0.50·$0.58입니다.
• 기준선 하나에 세 단계 사다리, 3초 480p 클립 네 개: $0.60.
• 레퍼런스→영상, 480p에서 5초: 이미지 하나면 $0.32, 둘이면 $0.34, 1080p에서 이미지 하나면 $1.37.
• 실패했거나 만료된 작업은 보통 과금되지 않지만, 마음에 들지 않는 완성 클립은 과금됩니다.
• 레퍼런스 클립을 포함한 견적은 클립 15초를 전부 예약합니다. 480p에서 5초 결과면 $1.20이며, 실제 과금은 클립의 실제 길이로 정산됩니다.

480p, 3초로 드래프트한 뒤, 남길 것을 같은 seed로 768p나 1080p에서 한 번만 다시 보내세요. 복사가 아니라 가까운 변형을 기대하세요.

LoRA가 아무 일도 하지 않거나 클립이 어긋날 때

무검열 사용

SpicyAPI는 프롬프트, 가중치, 결과물에 콘텐츠 필터를 추가하지 않습니다. 그 테스트에서 우리 콘텐츠 단계로 인한 거부는 없었습니다. 단계는 L1 Suggestive에서 L2 Mature themes, L3 Strong, L4 Intense로 이어지고, 여기에 L5a Restraint와 L5b Gore 탐침이 붙으며, LoRA를 불러오지 않은 상태였습니다. 한 군데가 약했습니다. LoRA 없이 이미지→영상은 세 번 실행 중 두 번에서 L4 Intense(성인 두 사람 사이의 친밀한 장면)를 완화했습니다. 반면 텍스트와 레퍼런스 입력은 모든 단계를 그대로 렌더링했습니다. 커뮤니티 성인 LoRA를 불러오면 세 작업 모두 L4를 렌더링했습니다. 전체 결과는 H3 LoRA 리뷰에 있습니다.

SpicyAPI가 추가 콘텐츠 필터를 넣지 않는다고 해서 닮은 얼굴을 쓸 권리가 생기는 것은 아닙니다. 나오는 사람이 모두 성인이어야 하고, 실제 사람의 LoRA는 그 사람의 동의와 그 얼굴에 대한 이용 권한이 필요합니다.

실시간 가격이 보이는 MiniMax H3 LoRA playground에서 직접 해보세요.

자주 묻는 질문

Hugging Face 리포지토리 이름이나 /blob/ 링크를 붙여 넣을 수 있나요?

안 됩니다. path는 파일로 가는 직접 HTTPS 링크만 받습니다. /blob/ 페이지나 owner/repo 이름만 넣으면 400으로 거부되며, 일부 호스트가 받는 weight_name 필드에는 여기서 대응하는 것이 없습니다. /resolve/ 링크를 쓰세요.

직접 학습한 LoRA를 불러올 수 있나요?

가능합니다. 오픈 웨이트 H3로 학습했고 .safetensors로 저장했으며 HTTPS로 접근할 수 있다면 됩니다.