블로그

튜토리얼

hiapi에서 curl과 Python으로 minimax-h3-image 이미지-투-이미지 호출하는 방법

Nov 13, 2026
hiapi.ai 블로그 커버 이미지: 짙은 소나무색 바탕 위에 깔끔한 사선으로 평면 색면이 나뉜 추상 프리즘 기하 구성
이 페이지에서

이미지-투-이미지 엔드포인트가 기대하는 것

코드를 작성하기 전에 이미지-투-이미지 호출의 구조를 이해하는 것이 도움이 됩니다. minimax-h3-image 이미지-투-이미지 엔드포인트는 참조 이미지(한 장 이상)와 텍스트 프롬프트를 받아, 프롬프트를 따르면서 동시에 참조 이미지에 고정된 완전히 새로운 생성 결과를 반환합니다.

개념적으로 모든 요청은 세 부분으로 구성됩니다:

  • 모델 라우팅 — image-to-image 작업으로 minimax-h3-image를 지정하며, 모든 것이 단일 hiapi 엔드포인트를 통해 이루어집니다. 능력별로 별도의 자격 증명이나 호스트를 준비할 필요가 없습니다.
  • 입력 — 프롬프트 문자열, 한 장 이상의 참조 이미지(URL 또는 base64 페이로드), 그리고 해상도 등급과 같은 생성 제어 항목.
  • 출력 계약 — 호출은 비동기입니다. 작업 식별자를 돌려받은 다음 상태를 폴링하고, 작업이 완료되면 생성된 이미지 URL을 가져옵니다.

마지막 항목이 중요합니다. 이미지-투-이미지는 한 번의 응답으로 픽셀을 바로 주는 블로킹 호출이 아닙니다. 제출 호출을 "작업을 대기열에 넣는 것"으로 간주하고, 처음부터 작업 수명 주기를 중심으로 클라이언트를 설계하세요. 동기 동작을 전제로 설계하면 나중에 통합 코드를 다시 작성해야 합니다.

모든 것이 동일한 hiapi 인터페이스를 통해 흐르기 때문에 요청 헤더, 인증, 응답 래핑이 모델과 작업 전반에 걸쳐 일관됩니다. minimax-h3-image에 대해 한 번 익히면 동일한 패턴이 플랫폼의 다른 곳에도 적용됩니다.

최소 실행 가능 요청

자격 증명, 엔드포인트, 페이로드 구조가 모두 올바른지 증명하는 최소 요청부터 시작하세요. 처음부터 모든 선택 필드를 추가하려 서두르지 마세요.

최소 요청 본문은 다음을 포함합니다:

  • 모델 이름 minimax-h3-image
  • 작업 유형 image-to-image
  • 원하는 변환을 설명하는 prompt
  • 단일 참조 이미지 필드
  • 하나의 해상도 등급

개념적으로 페이로드는 대략 다음과 같습니다:

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "이 스케치를 흰 배경 위의 깔끔한 제품 렌더링으로 바꿔줘",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}

전송하고 작업 id가 반환되는지 확인한 다음, 수동으로 한두 번 폴링하여 상태 전환을 관찰하세요. 작업 id를 받았다면 연결성과 인증이 정상이며 실제 클라이언트 구축을 계속할 수 있습니다. 받지 못했다면 멈추고 오류 응답 본문을 읽으세요 — 보통 문제가 된 필드를 직접 알려줍니다.

이 요청을 스모크 테스트로 저장하세요. 이후 변경으로 파이프라인이 망가질 때 이 최소 요청을 다시 실행하면 문제가 페이로드에 있는지 주변 코드에 있는지 즉시 알려줍니다.

curl로 호출하기

curl은 원시 요청과 응답을 확인하는 가장 빠른 방법입니다. JSON 요청 본문을 파일에 작성하면 편집할 때 셸 인용 부호와 씨름할 필요가 없습니다.

cat > payload.json <<'JSON'
{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "이 사진을 수채화 일러스트 스타일로 바꿔줘",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}
JSON

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @payload.json

두 헤더가 주요 역할을 합니다: bearer 토큰이 포함된 Authorization과 Content-Type: application/json. 둘 다 버전 관리에서 멀리 두세요 — 키를 명령에 붙여 넣지 말고 환경 변수에서 읽으세요.

제출에 성공하면 반환된 작업 id를 캡처하고 폴링하세요:

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

응답에는 상태 필드가 있고, 완료 후에는 결과가 있습니다. jq로 관심 있는 필드만 추출하세요:

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'

이것은 페이로드를 디버깅하는 가장 간단한 방법이기도 합니다: curl은 클라이언트 라이브러리가 숨기는 것 없이 무엇을 보냈고 무엇이 반환되었는지 정확히 보여줍니다.

Python으로 호출하기

Python 버전은 curl 흐름을 그대로 반영해야 합니다: 제출, id 캡처, 종료 상태까지 폴링, 결과 가져오기. requests와 Session을 사용하면 연결 재사용과 기본 헤더를 한 번만 처리하면 됩니다.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

def submit(prompt: str, image: str, resolution: str = "1024") -> str:
    body = {
        "model": "minimax-h3-image",
        "task": "image-to-image",
        "input": {
            "prompt": prompt,
            "image": image,
            "resolution": resolution,
        },
    }
    resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]

def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"작업 {task_id}이(가) {timeout}초 내에 완료되지 않았습니다")

if __name__ == "__main__":
    task_id = submit(
        "이 이미지를 플랫 벡터 포스터로 바꿔줘",
        "https://example.com/reference.png",
    )
    print("제출됨:", task_id)
    result = poll(task_id)
    print(result)

핵심 세부 사항: raise_for_status()는 HTTP 오류를 조용한 실패 대신 예외로 바꿉니다. 폴링 루프에는 마감 시간과 간격이 모두 있습니다. 종료 상태는 명시적으로 판단합니다. 이미지 URL은 상태가 종료 상태에 도달한 후에만 결과 객체에서 파싱해야 하며, 절대 그 전에 해서는 안 됩니다.

여러 참조 이미지 사용하기

단일 참조 이미지로는 종종 부족합니다. 한 사진의 얼굴을 유지하면서 다른 사진의 구도를 빌리거나, 질감과 윤곽을 융합하고 싶을 수 있습니다. Minimax-h3-image 이미지-투-이미지는 복수형 image 필드를 통해 다중 참조 입력을 지원합니다.

구조적으로 input 객체는 단일 참조 이미지를 image 필드로 담을 수 있고, 여러 장이 있을 때는 images 배열을 사용합니다:

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "첫 번째 이미지의 인물을 유지하고, 두 번째 이미지의 배경 스타일을 사용해줘",
    "images": [
      "https://example.com/person.png",
      "https://example.com/background.png"
    ],
    "resolution": "1024"
  }
}

순서는 의미가 있습니다. 참조 인덱스 0이 주요 대상이고, 뒤의 항목은 보조 컨텍스트이므로 프롬프트의 표현을 보낸 순서와 일치시키세요. 결과가 특정 참조 이미지를 무시한다면 보통 필드가 고장 난 것이 아니라 프롬프트가 모호한 것입니다 — 어떤 이미지가 어떤 속성을 결정하는지 프롬프트에서 명확히 말하세요.

다중 참조 작업을 위한 실용 규칙:

  • 개수를 간결하게 유지하세요. 특정 프롬프트에 실제로 필요한 참조 이미지만 사용하세요; 추가하면 제어력이 희석됩니다.
  • 가능한 한 종횡비를 맞추세요 그래야 모델이 서로 충돌하는 구도를 조정할 필요가 없습니다.
  • 동일한 요청에서 공개 URL 또는 base64를 일관되게 사용하세요, 전송 방식을 혼용하지 마세요.

통합 중에 두 이미지 요청을 한 번 보내 두 참조 이미지가 모두 출력에 뚜렷이 영향을 주는지 검증한 다음, 그 위에 더 복잡한 로직을 구축하세요.

해상도 등급 선택하기

resolution 필드는 minimax-h3-image 이미지-투-이미지의 출력 등급을 선택합니다. 이는 단순한 외형적 손잡이가 아니라 계산량, 응답 지연, 그리고 최종적으로 처리해야 할 페이로드 크기를 바꿉니다.

어떻게 균형을 잡을까요:

  • 대상 시나리오를 만족하는 최소 등급을 선택하세요. 목록 보기의 썸네일에는 메인 비주얼 배너와 같은 등급이 필요하지 않습니다. 나중에 고해상도 출력을 다운샘플링하는 것은 시간과 비용을 모두 낭비합니다.
  • 지연이 해상도에 따라 증가할 것으로 예상하세요. 높은 등급일수록 요청당 더 많은 작업을 하므로, 폴링 시간 초과와 간격 예산이 선택한 등급을 반영해야 합니다.
  • 페이로드 크기에 주의하세요. base64 참조 입력과 고해상도 출력 모두 전송량을 늘립니다; 이미지를 많이 다룬다면 요청과 응답 본문을 주의하세요.

과금은 요청한 해상도 등급을 따릅니다 — 요청은 실행된 등급으로 청구되므로 작은 사용 사례에 과도한 등급을 쓰면 조용히 비용이 더 나갑니다. 가정을 하드코딩하지 말고 가격 패널의 실시간 요율을 확인하세요.

합리적인 통합 전략은 개발 단계에서 속도를 위해 중간 등급을 사용하고, 프롬프트와 참조 이미지 세트가 확정된 후 핵심 자산을 더 높은 등급으로 올리는 것입니다. 해상도를 늦게 변경하면 지연 측정이 무효가 되므로, 실제로 출시할 등급에서 벤치마크하세요.

비동기 수명 주기 처리하기

hiapi의 모든 이미지-투-이미지 호출은 같은 루프를 따릅니다: 제출, 작업 id 캡처, 종료 상태까지 폴링, 그런 다음 결과 가져오기. 이 루프를 견고하게 만드는 것이 프로덕션 수준 클라이언트 작업의 대부분입니다.

제출하고 기록하기

작업 id를 영구 핸들로 취급하세요. 제출 응답이 도착하자마자 다른 어떤 일보다 먼저 기록하세요 — 폴링 도중 프로세스가 충돌하면 이 id로 재생성하지 않고 복구할 수 있습니다.

백오프를 적용한 폴링

고정 2초 폴링은 대화형 사용에는 괜찮지만 긴 배치에는 낭비입니다. 짧은 간격으로 시작해 점차 늘리되 최대 간격에 상한을 두면 여전히 완료를 제때 감지할 수 있습니다.

def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
    return min(current * factor, cap)

종료 상태를 존중하기

성공 또는 실패일 때만 루프를 종료하세요. 비어 있지 않은 응답을 모두 "완료"로 처리하는 것이 가장 흔한 비동기 버그입니다 — 아직 존재하지 않는 결과를 읽게 됩니다.

모든 것에 경계를 두기

모든 HTTP 호출에 시간 초과를 설정하고 작업에 전체 마감 시간을 두세요. 마감 시간이 지나면 계속 맴돌지 말고 명확한 오류를 발생시키세요. 일시적 네트워크 오류의 경우 폴링을 백오프로 재시도하세요; 무작정 다시 제출하면 중복 작업이 발생합니다.

정리

결과를 가져오면 즉시 이미지 URL이나 바이트를 자체 스토리지에 영속화하세요. 작업 결과는 임시 핸들이며 애플리케이션의 장기 CDN이 아닙니다.

문제 해결 및 프로덕션 체크리스트

다음은 개발자들이 minimax-h3-image 이미지-투-이미지를 사용할 때 가장 먼저 마주치는 실패와 이를 방지하는 점검 항목입니다.

최초 실행 실패

  • 401 / 403 — bearer 토큰이 없거나, 만료되었거나, 앞뒤에 공백 문자가 있습니다. 요청을 실행하는 셸에 환경 변수가 내보내졌는지 확인하세요.
  • 422 또는 검증 오류 — 오류 응답 본문을 확인하세요; 보통 필드를 알려줍니다. 흔한 원인은 prompt를 input 내부가 아닌 최상위에 둔 것입니다.
  • JSON 형식 오류 — 전송 전에 jq .로 페이로드 파일을 검증하세요.

실행 중 실패

  • 작업이 절대 완료되지 않음 — 실제로 받은 id로 폴링하는지, 자리 표시자가 아닌지 확인하세요. 선택한 해상도 등급에 비해 마감 시간이 충분히 긴지 점검하세요.
  • "완료" 작업의 결과가 비어 있음 — 상태 필드를 정확히 읽으세요; 실패 상태도 응답 본문을 반환합니다.
  • 참조 이미지가 무시됨 — 모델을 탓하기 전에 프롬프트 표현과 참조 이미지 순서를 먼저 검토하세요.

출시 전 체크리스트

  • API 키와 기본 URL은 환경 변수에서 읽고, 절대 저장소에 커밋하지 않습니다.
  • 모든 HTTP 호출에 명시적 시간 초과가 있습니다.
  • 폴링은 경계가 있는 백오프와 하드한 전체 마감 시간을 사용합니다.
  • 종료 상태는 명시적으로 처리되며; 결과 파싱 분기로 빠지지 않습니다.
  • 결과는 애플리케이션이 다운로드해 저장하며, 작업 응답에서 핫링크하지 않습니다.
  • 다중 참조 프롬프트는 어떤 이미지가 어떤 속성을 제어하는지 명시합니다.
  • 해상도 등급은 실제 출시할 값에서 벤치마크되었습니다.
  • 로그에 작업 id를 기록하여 실패한 작업을 추적하고 복구할 수 있습니다.

문제가 생길 때마다 앞서의 최소 요청을 다시 실행하세요 — 페이로드에 문제가 있는지 주변 코드에 문제가 있는지 분리해 줍니다. 요청 구조, curl 및 Python 클라이언트, 다중 참조 처리, 그리고 규율 있는 폴링 루프를 갖추었으니 hiapi에서 minimax-h3-image 이미지-투-이미지를 안정적으로 출시하는 데 필요한 모든 것을 갖춘 것입니다.

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

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

API 문서 보기