MiniMax H3 Max API로 텍스트와 이미지에서 영상 생성하는 방법

이 가이드는 성공적인 요청까지의 최단 경로와 프로덕션에 필요한 검증, 폴링, 콜백, 저장, 폴백을 다룹니다. H3 Max 전용 문서 페이지가 공개되기 전에는 모델 페이지의 최신 라우트 계약에서 정확한 필드를 확인하세요.

EvoLink API 키를 만들고, MiniMax H3 Max 모델 페이지에서 실시간 견적을 확인하고, 워크플로에 2K나 더 넓은 레퍼런스가 필요할 수 있다면 H3 Max vs H3 가이드를 가까이 두세요.

사전 준비

첫 요청을 보내기 전에 다음을 확인하세요.

올바른 H3 Max 모델 ID 선택

1단계: 텍스트로 영상 생성 요청 보내기

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

주요 T2V 파라미터는 다음과 같습니다.

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

2단계: 첫/마지막 프레임 이미지로 영상 생성 요청 보내기

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

제공하는 각 이미지는 직접 접근 가능한 HTTP(S) URL을 사용해야 하며 현재 계약을 따라야 합니다.

• JPG, JPEG, PNG, WEBP, HEIC 또는 HEIF.
• 이미지당 최대 30 MB.
• 너비와 높이는 256에서 5,760픽셀 사이.
• 너비 대 높이 비율은 0.4에서 2.5 사이.
• 첫 프레임 최대 하나, 마지막 프레임 최대 하나.
• 전체 JSON 본문은 64 MB 이하; Base64와 mm_file://은 허용되지 않음.

3단계: 작업 상태 폴링

같은 Bearer 토큰으로 작업을 조회하세요.

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

단순한 폴링 정책은 계속 조회하는 대신 지터를 포함한 제한된 지수 백오프를 사용해야 합니다. 예를 들어 2초 근처에서 시작해 10-15초까지 늘리고, 애플리케이션이 정한 마감 시간에 중단하며, 저장된 작업 ID로 나중에 워커가 재개할 수 있게 합니다. API 계약은 H3 Max에 취소 기능을 제공하지 않으므로, 클라이언트 타임아웃을 업스트림 취소로 오해해서는 안 됩니다.

4단계: 프로덕션용 콜백 추가

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

현재 EvoLink 계약은 HTTPS를 요구하고, 사설 IP 대상은 거부하며, 최대 10초를 기다리고, 실패한 콜백은 최대 세 번 재시도합니다. 핸들러는 다음을 수행해야 합니다.

1. 애플리케이션에서 구성한 검증 메커니즘으로 요청을 인증합니다.
2. 작업 ID를 멱등성 키로 사용합니다.
3. 2xx 응답을 빠르게 반환합니다.
4. 다운로드와 무거운 후처리는 큐로 옮깁니다.
5. 필요하다면 최종 고객 납품 전에 콜백 상태를 작업 엔드포인트와 대조합니다.

폴링은 복구 경로로 계속 유지하세요. 웹훅은 지연되거나, 네트워크 정책에 의해 거부되거나, 애플리케이션 인프라에서 두 번 처리될 수 있습니다.

제출 전 요청 검증

카테고리별 오류 처리

HTTP 오류와 비동기 작업 실패를 분리하세요. 생성 호출은 성공했지만 이후 생성이 실패할 수 있습니다. 시크릿이나 민감한 원본 URL은 기록하지 않으면서 작업 ID, 라우트, 입력 클래스, 길이, 품질, 최종 상태, 오류 코드, 재시도 횟수, 폴백 결과를 로그에 남기세요.

프로덕션 핸드오프 설계

요청과 작업 관계 저장

제출 전에 자체 작업 ID를 만드세요. EvoLink 작업 ID, 모델 ID, 정규화된 파라미터, 고객/워크스페이스 ID, 타임스탬프, 납품 상태를 저장합니다. 이렇게 하면 워커가 재시작되더라도 재시도, 감사, 지원이 가능합니다.

완료된 결과를 즉시 다운로드

H3 Max 결과 URL은 24시간 동안 유효합니다. 승인된 결과를 영구 저장소로 복사하고 체크섬이나 객체 키를 기록하세요. 임시 원본 URL을 고객의 영구 에셋으로 삼지 마세요.

재시도를 명시적으로

폴링 요청이 타임아웃되었다고 새 생성을 제출하지 마세요. 먼저 저장된 작업 ID를 조회하세요. 원래 작업이 최종 실패 상태에 도달했고 재시도 정책이 과금되는 추가 시도를 허용할 때만 새 작업을 만드세요.

호출 전에 호환되지 않는 작업 라우팅

승인 결과물 측정

다음을 추적하세요.

• 작업 성공률과 완료 지연 시간;
• 첫 시도 승인율과 재시도율;
• 승인 클립당 비용;
• 프롬프트, 정체성, 키프레임 준수;
• 심사 및 잘못된 요청 비율;
• 폴백 빈도와 복구율;
• URL 만료 전 다운로드 완료율.

흔한 통합 실수

출시 체크리스트

1. API 키가 서버 측에 있고 교체할 수 있습니다.
2. T2V와 I2V가 별도의 검증 스키마를 사용합니다.
3. 길이, 품질, 종횡비, 이미지 제한이 로컬에서 강제됩니다.
4. 워커가 종료되기 전에 생성 응답의 id가 저장됩니다.
5. 폴링이 제한된 백오프를 사용하고 재개할 수 있습니다.
6. 콜백 처리가 멱등하고 폴링이 계속 사용 가능합니다.
7. 완료된 MP4 파일이 24시간 이내에 복사됩니다.
8. 로그가 요청 오류, 작업 실패, 리뷰 거부를 분리합니다.
9. 가격은 하드코딩된 블로그 값이 아니라 현재 모델 페이지나 가격 서비스에서 가져옵니다.
10. 호환되지 않거나 실패한 작업을 위해 H3과 독립적인 폴백 하나를 테스트했습니다.

자주 묻는 질문

MiniMax H3 Max는 EvoLink에서 어떤 엔드포인트를 사용하나요?

어떤 모델 ID를 사용해야 하나요?

H3 Max API는 동기식인가요?

4초짜리 H3 Max 영상을 생성할 수 있나요?

아니요. 지원되는 길이는 5초부터 15초까지의 정수입니다. EvoLink에서 4초 하한을 지원하는 것은 H3 Max가 아니라 MiniMax H3입니다.

마지막 프레임만 사용할 수 있나요?

네. 이미지로 영상 생성 모델은 첫 프레임만, 마지막 프레임만, 첫+마지막 프레임 요청을 모두 받습니다.

Base64 이미지를 보낼 수 있나요?

이미지로 영상 생성에서 종횡비를 받나요?

보내지 마세요. 출력은 제공된 프레임 비율을 따릅니다. 원본 프레임을 의도한 납품 형식에 맞게 준비하세요.

결과 URL은 얼마나 오래 유효한가요?

24시간입니다. 납품 워크플로의 일부로 완료된 MP4 파일을 영구 저장소로 복사하세요.

현재 가격은 어디서 확인해야 하나요?

H3 Max 제품 페이지의 실시간 가격 섹션과 견적 도구를 사용하세요. 블로그의 단가를 프로덕션 예산에 하드코딩하지 마세요.

API 레퍼런스 및 검증 범위

• EvoLink MiniMax H3 Max 모델 페이지 및 현재 라우트 계약
• EvoLink 비동기 작업 상태 레퍼런스
• MiniMax 공식 Video Generation V2 문서