블로그

튜토리얼

HiAPI API를 통해 minimax-h3-max-turbo/image-to-video를 사용하는 방법: curl, Python 및 사용 가능한 요청 예시

Nov 17, 2026
따뜻한 모래색 배경을 가로질러 계단식으로 내려가는 테라코타와 엄버 색상의 넓은 가로 띠가 돋보이는 추상 커버 아트로, 평면적인 인쇄 가장자리를 지니고 있다.
이 페이지에서

이 엔드포인트가 하는 일과 사용 시점

minimax-h3-max-turbo/image-to-video는 소스 이미지 하나와 텍스트 프롬프트 하나를 받아, 해당 이미지를 시작점으로 하는 짧은 영상을 반환합니다. 이미지는 첫 프레임(또는 시각적 기준점) 역할을 하므로 출력은 그 구도, 색조, 주체 정체성을 이어받습니다. 그다음 프롬프트가 이후에 무슨 일이 일어나야 하는지—카메라 움직임, 주체 동작, 분위기—를 설명합니다.

텍스트 투 비디오 대신 이것을 선택할 때

참조할 시각 자료가 없고 모델이 모든 것을 창작하기를 원할 때는 텍스트 투 비디오가 적합한 도구입니다. 첫 프레임 자체가 핵심일 때는 이미지 투 비디오가 올바른 선택입니다. 이미 승인된 제품 사진, 스토리보드 키프레임, 캐릭터 디자인 또는 사용자 업로드 사진이 있고, 이것이 알아볼 수 있는 상태로 움직여야 하는 경우가 그렇습니다. 구체적으로 팀은 다음 상황에서 이 엔드포인트를 사용합니다:

  • 첫 프레임이 계약 요건인 경우. 마케팅 팀은 유사한 이미지가 아니라 정확한 메인 이미지로 시작해야 합니다.
  • 클립 간 일관성이 중요한 경우. 동일한 소스 이미지를 재사용하면 일련의 클립에서 캐릭터나 제품이 안정적으로 유지됩니다.
  • 사용자 콘텐츠를 움직이게 하는 경우. 최종 사용자가 업로드한 사진은 재해석되는 것이 아니라 애니메이션화되어야 합니다.
  • 프롬프트 범위를 더 좁히고 싶은 경우. 장면 전체를 처음부터 설명하는 것보다 움직임을 설명하는 것이 더 쉽기 때문에 프롬프트가 짧고 예측 가능하게 유지됩니다.

이 엔드포인트는 비동기식입니다. 작업을 제출한 다음 렌더링된 비디오를 가져옵니다. 이 형태는 큐 기반 백엔드에 잘 맞으며, 자세한 내용은 아래에서 다룹니다. 전체 매개변수 범위는 모델 페이지를 참조하세요.

사전 요구 사항과 요청 구조

엔드포인트를 호출하기 전에 네 가지를 확인하세요:

  1. API 키. HiAPI 계정에서 생성하고 bearer token 형태로 전송합니다. 기밀로 취급하세요—클라이언트 코드에 절대 포함하지 마세요.
  2. 기본 URL. 모든 요청은 HiAPI 통합 API 호스트로 전송되며, 엔드포인트 경로가 곧 모델 식별자입니다.
  3. 소스 이미지 하나—접근 가능하거나 인코딩 가능한 형태로. 요청 스키마가 허용하는 형식에 따라 공개 HTTPS URL 또는 base64 페이로드입니다.
  4. HTTP 클라이언트—스모크 테스트용 curl, 실제 통합용으로는 Python의 표준 라이브러리 또는 requests.

요청의 구성 요소

어떤 언어를 사용하든 모든 작업 제출은 동일한 개념적 요소를 포함합니다:

  • 모델 / 엔드포인트—minimax-h3-max-turbo/image-to-video, 요청 경로의 일부이며 명확성을 위해 요청 본문에도 반복됩니다.
  • 소스 이미지—첫 프레임. 이미지 투 비디오와 텍스트 투 비디오를 구분하는 필드이며, 검증 오류를 가장 쉽게 유발하는 필드이기도 합니다.
  • 프롬프트—움직임과 장면 설명. 이미지에 이미 존재하는 내용이 아니라 변할 내용만 설명하세요.
  • 선택적 생성 힌트—엔드포인트가 제공하는 경우 길이 및 해상도 스타일 제어. 스키마 문서에 기록된 매개변수만 전송하세요. 알 수 없는 키는 4xx 응답의 흔한 원인입니다.

제출은 작업 식별자와 상태를 반환합니다. 비디오 자체는 두 번째 요청으로 나중에 도착합니다—그래서 아래의 폴링 부분이 제출 호출만큼 중요합니다.

사용 가능한 curl 요청

다음 명령은 이미지 투 비디오 작업을 제출합니다. 실행하기 전에 꺾쇠괄호 안의 대문자 자리 표시자를 자신의 값으로 바꾸세요.

curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": "Slow push-in on the product, soft studio light shifting across the surface, shallow depth of field."
  }'

이 명령에 대한 실용적인 참고 사항:

  • 키를 환경 변수에서 읽으세요. $HIAPI_API_KEY를 내보내기하면 인라인으로 붙여넣는 대신 키가 셸 기록에 남는 것을 피할 수 있습니다.
  • 첫 테스트에는 공개 이미지 URL을 사용하세요. 이렇게 하면 base64 인코딩 요소를 배제하면서 인증과 연결이 정상 작동하는지 확인할 수 있습니다.
  • JSON 요청 본문을 작게 유지하세요. -d 페이로드가 요청 전체입니다. 여기서 쉼표 하나가 빠지면 명확한 스키마 오류 대신 혼란스러운 400이 발생합니다.
  • 프롬프트를 따옴표로 감싸세요. 구두점이 포함된 프롬프트는 따옴표 없는 셸 문자열을 깨뜨립니다.

응답은 비디오가 아니라 작업 객체입니다. 여기서 작업 ID를 캡처하세요—이 ID를 폴링 요청에 사용하게 됩니다. 호출이 즉시 실패하면 문제 해결 섹션으로 넘어가세요. 인증 및 페이로드 오류는 나중이 아니라 이 단계에서 드러납니다.

Python에서의 동일한 요청

다음은 requests를 사용한 Python 등가 제출 호출입니다. 환경 변수에 HIAPI_API_KEY가 설정되어 있다고 가정합니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"

payload = {
    "model": "minimax-h3-max-turbo/image-to-video",
    "image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
    "prompt": (
        "Slow push-in on the product, soft studio light shifting "
        "across the surface, shallow depth of field."
    ),
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))

이 스니펫을 각색할 때 유지해야 할 핵심 사항:

  • 타임아웃은 선택 사항이 아닙니다. 제출은 빠르지만 웹 요청 핸들러에서 멈춘 소켓은 워커까지 함께 끌어내립니다.
  • 파싱 전에 raise_for_status()를 호출하세요. 조용한 401을 실제로 기록할 수 있는 예외로 바꿔줍니다.
  • 응답이 아니라 작업 ID를 반환하세요. 서비스에서는 제출 함수가 식별자를 반환하고, 별도의 폴러나 백그라운드 작업이 대기를 담당해야 합니다.
  • 페이로드를 변수에 보관하세요. 호출이 성공한 후 이미지 URL을 서명된 업로드 URL이나 base64 문자열로 바꾸는 것은 한 줄 수정일 뿐입니다.

여기서는 의도적으로 래퍼 라이브러리 대신 일반 HTTP 클라이언트를 사용합니다. 요청 형태가 곧 계약이며, 기술 스택이 사용하는 어떤 언어에서도 이를 재현할 수 있어야 합니다.

이미지와 첫 프레임 준비

실패한 이미지 투 비디오 작업의 대부분은 프롬프트가 아니라 이미지에서 실패합니다. 몇 가지 습관으로 이를 피할 수 있습니다.

형식과 전달

표준적이고 널리 지원되는 래스터 형식—JPEG 또는 PNG—을 사용하고, URL이 쿠키 없이 접근 가능하며 로그인 페이지로 리디렉션되지 않고 제출 후 생성되는 만료된 서명에 의존하지 않는지 확인하세요. 리소스가 프라이빗 버킷에 있다면 작업 예상 실행 시간보다 훨씬 긴 수명의 서명 URL을 생성하세요. base64 페이로드의 경우 스키마가 원시 인코딩 바이트를 기대한다면 data-URI 프리픽스를 제거하고, 인코딩 후 크기가 문서 제한 내에 충분히 들어오는지 확인하세요.

크기와 구도

모델은 고정 출력 크기로 비디오를 렌더링하므로 소스 이미지는 맞춤 처리됩니다. 두 가지 결과가 있습니다:

  • 원하는 화면 비율과 일치시키세요. 세로 인물 사진을 가로 렌더링에 넣으면 잘리거나 검은 띠가 생기고, 주체가 중앙에서 벗어날 수 있습니다.
  • 움직임을 위한 여유를 두세요. 프롬프트가 카메라 푸시인이나 주체의 위쪽 이동을 설명한다면 소스 이미지에서 그 방향으로 공간을 남겨두세요.

첫 프레임을 온전하게 유지

오프닝 프레임은 주로 이미지 자체에 달려 있습니다. 프롬프트는 첫 프레임이후에 일어나는 일에 대한 지시로 작성하세요. 카메라 동작, 주체 동작, 조명 변화를 설명합니다. 장면을 다시 설명하는 것은 피하세요—이미지가 "흰 바닥 위의 빨간 의자"를 보여주는데 이를 반복 설명하면 충실도보다 드리프트가 늘어나는 경우가 많습니다. 결과가 소스 이미지에서 벗어나면 먼저 프롬프트를 줄이고, 그다음에 이미지 교체를 고려하세요.

문서화되지 않은 매개변수가 있다고 가정하지 마세요. 원하는 제어 항목이 스키마에 없다면 프롬프트나 이미지 준비를 통해 구현하세요.

비동기 작업 수명 주기 처리

이미지 투 비디오 작업은 동기식이 아닙니다. 패턴은 제출 → 폴링 → 가져오기이며, 프로덕션 통합은 세 단계를 모두 명시적으로 구현해야 합니다.

1. 제출하고 영속화하기

제출 요청을 보내고 반환된 작업 ID를 즉시 저장하세요. 가능하면 자체 상관 ID, 요청 페이로드 해시, 타임스탬프와 함께 저장하는 것이 좋습니다. 제출과 저장 사이에 프로세스가 죽으면 가져올 수 없는 작업에 비용을 지불한 셈입니다.

2. 백오프를 적용한 폴링

저장한 ID로 작업 상태 엔드포인트를 폴링하세요. 비디오 렌더링은 이미지 생성보다 확실히 오래 걸리므로:

  • 적당한 간격—몇 초—으로 시작하고, 고정 속도로 엔드포인트를 두드리는 대신 작업 시간이 길어질수록 간격을 늘리세요.
  • 총 대기 시간을 작업에 적합한 상한으로 제한한 다음 작업을 타임아웃으로 처리하고 재시도 여부를 결정하세요.
  • 종료 상태는 종료 상태로 취급하세요. 작업이 성공 또는 실패를 보고하면 폴링을 중단하세요.
import time

def wait_for_job(poll_fn, job_id, max_wait=600):
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        job = poll_fn(job_id)
        if job["status"] in ("succeeded", "failed"):
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

3. 출력 가져오기와 저장

성공 후 작업 객체는 결과 위치를 담고 있습니다. 비디오를 즉시 다운로드하고 자체 스토리지로 복사하세요. 출력 URL은 영구 자산 라이브러리가 아니라 임시 리소스로 취급해야 합니다. 지원 담당자가 모든 클립을 원래 요청으로 추적할 수 있도록 저장 파일 옆에 작업 ID를 기록하세요.

재시도의 경우 이미 저장한 ID의 작업만 다시 폴링하세요. 맹목적으로 다시 제출하지 마세요. 그렇지 않으면 중복 렌더링과 중복 청구가 발생합니다.

일반 오류 문제 해결

인증 실패(401 / 403)

먼저 Authorization 헤더를 확인하세요. Bearer 단어, 공백 하나, 그다음 키가 있어야 하며, 키를 복사할 때 붙은 후행 개행 문자가 없어야 합니다. 키가 활성 상태이고 원하는 계정에 속하는지 확인하세요. curl은 되는데 Python은 안 되면 헤더 길이를 출력해 보세요. 빈 환경 변수는 겉보기에 유효하지만 쓸모없는 토큰을 만들어냅니다.

잘못된 형식 또는 지원되지 않는 이미지 페이로드(400 / 422)

인증 외 실패 중 가장 흔한 경우입니다. 순서대로 확인하세요:

  • 이미지 URL이 올바르게 해석되고 HTML 로그인 페이지로 리디렉션되지 않는지.
  • 형식이 JPEG 또는 PNG인지, WebP, HEIC 또는 PDF 썸네일이 아닌지.
  • 인코딩 또는 다운로드 후 크기가 문서 제한 내에 있는지.
  • Base64 페이로드에 data: 프리픽스가 없고 줄바꿈으로 인한 공백도 없는지.
  • 이미지가 손상되지 않았는지. API를 탓하기 전에 먼저 스스로 가져와서 열어보세요.

알 수 없거나 잘못된 매개변수

필드 이름의 철자가 틀렸거나 엔드포인트가 노출하지 않는 매개변수는 일반적으로 해당 필드를 지목하는 검증 오류를 반환합니다. 추측성 매개변수를 제거하고 문서가 규정한 최소 요구 사항에서 다시 구성하세요.

속도 제한(429)

지수 백오프를 적용하고 응답에 포함된 재시도 힌트를 따르세요. 타이트 루프에서 재시도하지 마세요. 제한이 심해집니다. 자주 발생한다면 사용자 요청에서 인라인으로 트리거하는 대신 큐를 통해 일괄 제출하세요.

작업 타임아웃과 폴링 멈춤

작업이 예산 내에서 종료 상태에 도달하지 않으면 작업 ID와 상태 이력을 기록하고 폴링을 중단하세요. 지속적인 타임아웃은 보통 제출 시 이미지가 너무 크거나 비정상임을 나타내므로 이미지 준비 섹션을 다시 확인하세요. 시도 횟수 상한 없이 자동으로 다시 제출하지 마세요.

출시 전 프로덕션 체크리스트

이 엔드포인트가 실제 트래픽에 가까워지기 전에 다음 각 항목을 확인하세요:

  • 곳곳에 타임아웃이 있음. 제출에는 짧은 타임아웃, 폴링에는 총 대기 상한, 재시도 시도에는 하드 상한이 있습니다. 무한 while True 루프는 없어야 합니다.
  • 백오프를 적용한 재시도. 429와 일시적 5xx 응답을 재시도하세요. 검증 오류는 절대 재시도하지 마세요. 같은 방식으로 실패합니다.
  • 로그에 작업 ID가 있음. 각 요청에 대해 작업 ID, 자체 상관 ID, 최종 상태를 기록하세요. 이것이 보존할 수 있는 가장 유용한 디버깅 산출물입니다.
  • 출력이 자체 스토리지에 저장됨. 완료된 비디오를 반환 URL에서 영구 스토리지로 복사하고, 재현성을 위해 소스 이미지 참조를 보관하세요.
  • 에지에서 이미지 검증. API에 도달하기 전에 잘못된 형식과 과대 업로드를 거부하여 사용자가 몇 분 후 비동기 실패가 아니라 즉시 명확한 오류를 받도록 하세요.
  • 비용 인식. 생성은 렌더링된 비디오 출력 단위로 청구되므로 사용자 또는 기능별 작업량과 길이를 추적하세요. 가정을 코드나 문서에 하드코딩하지 말고 현재 가격 패널을 확인하세요.
  • 카나리 프롬프트. 테스트 스위트에 알려진 양호한 이미지와 프롬프트 세트를 유지하고, 통합 변경 후 이를 실행하여 요청 계약이 여전히 유효한지 확인하세요.

비동기 수명 주기—제출, 영속화, 폴링, 저장—을 올바르게 처리하면 이 엔드포인트는 단순합니다. 모델 페이지에서 정확한 스키마를 가져온 다음 위의 제출 및 폴링 패턴을 연결하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기