블로그

튜토리얼

HiAPI API로 minimax-h3-image 텍스트-이미지 생성 사용하기: curl과 Python

Nov 13, 2026
평직 직조 스타일 커버 이미지: 짙은 갈색과 오트밀색의 넓은 천 밴드가 교차하는 사각형 직조 패턴에 소량의 황동색 위사가 포인트로 들어가 있습니다.
이 페이지에서

이 튜토리얼에서 다루는 내용과 먼저 준비해야 할 것

이 튜토리얼은 한 가지 구체적인 일만 다룹니다: HiAPI API를 통해 minimax-h3-image 텍스트-이미지 모델에 이미지 생성 프롬프트를 보내고, 먼저 curl 요청으로 한 번 수행한 다음 애플리케이션에 넣을 수 있는 작은 Python 함수로 구현합니다. 요청의 구조, 응답을 해석하는 방법, 오류가 드러나는 방식, 그리고 프로덕션 출시 전에 조여야 할 부분을 다룹니다.

의도적으로 프롬프트 엔지니어링 이론, 이미지 후처리, UI 구축은 다루지 않습니다. 목표는 더 집중되어 있습니다: 읽고 나면 신뢰할 수 있는 요청을 갖게 되고, 지난번에 실패한 정확한 이유를 알게 됩니다.

전제 조건

  • HiAPI 계정. 무엇보다 먼저 프로젝트와 API 키가 필요합니다—아래의 모든 요청에는 인증이 필요합니다.
  • 키를 안전한 곳에 보관하세요. 소스 파일이 아니라 환경 변수(HIAPI_API_KEY)에 넣으세요. 그러면 동일한 코드가 로컬과 CI에서 모두 작동합니다.
  • 모델 식별자. 이 튜토리얼은 minimax-h3-image와 그 text-to-image 기능을 사용합니다. 모델 이름과 작업 경로를 코드 곳곳에 흩어진 매직 문자열이 아니라 구성 값으로 취급하세요.
  • 도구. 첫 요청에는 curl, 두 번째에는 Python 3.9+와 requests를 사용합니다. 다른 라이브러리는 필요하지 않습니다.
  • 이미지를 볼 방법. 이미지 데이터나 이미지에 대한 참조를 포함하는 응답 페이로드를 읽게 됩니다—어떤 스키마든 가정하기 전에 응답 필드를 한 번 직접 확인하세요.

지금부터 들여야 할 습관

애플리케이션 코드 밖에서 첫 번째 성공적인 요청을 먼저 만드세요. 작동하는 curl 명령은 기준 진실입니다: Python 버전이 이상하게 동작할 때마다 그것과 대조하세요. curl 호출은 성공하는데 Python은 그렇지 않다면, 문제는 모델이나 네트워크가 아니라 클라이언트에 있습니다.

curl로 동작하는 텍스트-이미지 요청 만들기

가능한 한 최소한의 요청으로 시작한 다음 설정을 하나씩 다시 추가하세요. 생성 요청은 세 부분으로 구성됩니다: 엔드포인트, 인증 헤더, JSON 요청 본문.

요청

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "task": "text-to-image",
    "prompt": "린넨 식탁보 위의 도자기 그릇, 부드러운 북향 창빛, 50mm 렌즈, 얕은 심도",
    "size": "1024x1024",
    "n": 1
  }'

그 명령에서 주의할 점은 세 가지입니다:

  • 키는 bearer 토큰으로 Authorization 헤더에 담겨 전달됩니다. URL이나 요청 본문에 절대 넣지 마세요. 그러면 로그와 셸 기록에 남습니다.
  • model과 task는 무엇을 원하는지 설명합니다—모델 계열과 기능. 기본값이 있더라도 둘 다 명시적으로 작성하세요. 명시적 요청이 시간이 지나도 더 잘 견딥니다.
  • prompt는 일반 문자열입니다. 나머지(size, n)는 피사체 설명이 아니라 이미지 설정입니다.

응답 해석

출력을 포매터에 통과시켜 실제로 읽을 수 있게 하세요:

curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

반복 작업 중에는 요청 본문을 파일(request.json)에 넣으세요—그러면 프롬프트가 읽기 쉬운 상태로 유지되고, 프롬프트 수정이 따옴표 추측 게임이 아니라 한 줄 diff가 됩니다.

파서를 작성하기 전에 페이로드를 확인하세요. 이미지가 인라인으로 반환되는지 URL로 반환되는지, 어떤 필드가 이미지 식별자와 수정된 프롬프트를 담는지, 응답에 사용량 메타데이터가 포함되는지 확인하세요. 이 필드 이름들을 적어 두세요. Python 클라이언트가 이들에 의존하게 됩니다.

전체 흐름을 끝까지 확인하기

반환된 이미지를 저장하고, 열어 보고, 요청한 것이 정확히 수신되었는지 확인하세요. 그럴듯한 JSON 본문과 함께 온 200 응답이 올바른 이미지를 의미하지는 않습니다—바로 이 지점에서 프롬프트와 파라미터 문제를 가장 저렴하게 발견할 수 있습니다.

요청을 Python으로 옮기기

이제 완전히 동일한 요청을 이식하세요. 평범하게 유지하세요: 함수 하나, 명시적 타임아웃, 당분간 숨은 재시도 없음.

import os
import requests

HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"


def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    """HiAPI를 통해 minimax-h3-image로 이미지를 생성합니다."""
    payload = {
        "model": "minimax-h3-image",
        "task": "text-to-image",
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=(5, 120),  # 연결 타임아웃, 읽기 타임아웃
    )
    response.raise_for_status()
    return response.json()

그 함수에는 네 가지 의도적인 선택이 있습니다:

  • 튜플 타임아웃. 연결 타임아웃은 짧게 두었습니다. 연결 설정이 느리다는 것은 문제가 있다는 뜻이기 때문입니다. 읽기 타임아웃은 넉넉하게 두었습니다. 이미지 생성은 원래 시간이 걸리기 때문입니다. 단일 타임아웃 값은 하나의 실패 모드에서만 잘 처리하도록 강제합니다.
  • json=payload. 라이브러리가 요청 본문을 직렬화하게 하세요. 손으로 이어 붙인 JSON 문자열은 따옴표 버그의 온상입니다.
  • 파싱 전에 raise_for_status(). 상태 확인은 선택 사항이 아닙니다—오류 응답 본문을 성공으로 파싱하는 것이 이런 통합에서 가장 혼란스러운 버그 유형입니다.
  • 일반 dict 반환. 나중에 타입 지정 모델로 감쌀 수 있습니다. 먼저 응답이 실제로 어떤 필드를 포함하는지 아는 것이 중요합니다.

키 조회를 분리하기

변수가 없으면 os.environ["HIAPI_API_KEY"]는 즉시 예외를 던집니다. 이는 의도된 것입니다: 첫 사용자 요청이 아니라 시작 시 실패하도록 하기 위해서입니다. 더 큰 코드베이스에서는 구성 로드 중에 키를 한 번 해석한 다음, 호출 지점에서 환경 변수를 읽는 대신 구성된 클라이언트를 전달하세요.

실행에 연결하기

if __name__ == "__main__":
    result = generate_image("썰물 때 젖은 해변 위의 빨간 연, 흐린 날씨의 빛")
    print(result)

실행하고 curl 출력과 비교하세요. 페이로드 구조가 일치해야 합니다. 일치하지 않으면 계속 구축하기 전에 반드시 알아내야 할 차이를 발견한 것입니다.

추측이 아니라 오류 처리

가장 흔한 통합 버그는 절대 성공하지 않을 오류를 재시도하는 것입니다. 실패를 세 가지 범주로 나누고 다르게 처리하세요.

인증 및 권한 부여 실패

일반적으로 401 또는 403으로 나타납니다. 원인은 헤더 누락, Bearer 접두사 형식 오류, 키 폐기 또는 잘못된 구성, 또는 프로젝트가 해당 모델에 대한 접근 권한이 없는 경우입니다. 이들은 재시도 불가입니다. 재시도는 시간을 낭비하고 동일한 실패로 로그를 오염시킬 뿐입니다. 자격 증명을 고치고 계속 진행하세요.

요청 유효성 검사 실패

일반적으로 400 수준 응답입니다: 알 수 없는 model 또는 task 값, 모델이 지원하지 않는 size, 범위를 벗어난 n, 빈 프롬프트, 잘못된 형식의 JSON. 이들 역시 재시도 불가입니다—동일한 요청은 동일하게 실패합니다. 유용한 작업은 요청을 작성한 개발자에게 오류 메시지를 그대로 보여주는 것이지, 일반 예외에 삼켜 버리는 것이 아닙니다.

일시적 서버 및 네트워크 실패

429 및 5xx 응답, 연결 재설정, 읽기 타임아웃이 실제로 재시도 가능한 범주입니다. 상한이 있는 지수 백오프와 지터로 처리하세요:

import time, random, requests

def post_with_retry(session, url, payload, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            r = session.post(url, json=payload, timeout=(5, 120))
            if r.status_code in (429, 500, 502, 503, 504):
                raise requests.HTTPError(f"일시적 오류 {r.status_code}", response=r)
            r.raise_for_status()
            return r.json()
        except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
            if attempt == max_attempts - 1:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))

두 가지 주의 사항. 첫째, 429가 아닌 4xx에서 발생한 HTTPError는 즉시 외부로 던져야 합니다—except 절이 유효성 검사 실패를 흡수하게 두지 마세요. 둘째, 응답에 포함된 재시도 지침을 따르고 지연을 직접 만들어내지 마세요.

여기서 재시도는 멱등하지 않습니다

재시도된 생성은 매번 새로운 과금 생성입니다. 요청이 타임아웃되면 이미지가 여전히 생성되고 과금되었을 수 있습니다. 재시도 횟수를 작게 유지하고, 로그에 시도 횟수를 요청 메타데이터와 함께 기록하며, 동일한 이미지를 조용히 네 번 생성하기보다 명확한 실패를 드러내는 것을 우선하세요.

프롬프트와 파라미터에 대한 실용적인 위생 습관

이 습관들의 의미는 비교 가능성에 있습니다: 한 가지를 바꿀 때 출력 변화가 그로 인한 것인지 판단할 수 있어야 합니다.

화면 내용을 명시하는 프롬프트 작성

피사체, 장면, 조명, 구도의 순서로 설명하세요. 구체적인 명사와 사진 용어(예: "부드러운 북향 창빛", "얕은 심도")는 미학적 형용사를 쌓는 것보다 더 많은 신호를 담습니다. 부정 프롬프트를 많이 사용하지 마세요. 나타나야 할 내용을 설명하세요.

한 번에 하나의 변수만 변경

프로젝트마다 작은 프롬프트 파일을 유지하고, 처음부터 다시 작성하는 대신 실행 사이에 편집하세요. 어떤 실행이 실망스럽다면 프롬프트를 바꾸거나 설정을 바꾸세요—둘 다 바꾸지 마세요. 그렇지 않으면 어떤 변경이 효과가 있었는지 알 수 없습니다.

설정을 명시적 계약으로 취급

size와 n은 출력과 비용 모두에 영향을 미칩니다. 리터럴을 호출 지점마다 꿰어 넣는 대신 구성 객체에 고정하세요. 그러면 전체 기능의 가로세로 비율 변경이 한 번의 편집이 됩니다. 비교를 위해 여러 이미지가 필요하면 여러 번 호출하는 대신 한 번의 호출로 요청하세요—왕복이 줄고 로그가 읽기 쉬워집니다.

프롬프트를 출력과 함께 저장

생성된 각 이미지 옆에 정확한 프롬프트 문자열, 설정, 모델 식별자를 영구 저장하세요. 재현할 수 없는 프롬프트는 다시 생성, 디버깅, 개선할 수 없는 이미지입니다. 이 하나의 습관이 어떤 프롬프트 요령보다도 시간을 절약합니다.

비교를 위한 시드 설정

동일한 프롬프트가 실행마다 다른 이미지를 생성할 수 있습니다. 변경 사항을 평가할 때는 단일 운 좋은 또는 운 나쁜 샘플을 믿지 말고 집계 결과—구성당 여러 이미지—를 비교하세요.

프롬프트 버전 관리

프롬프트 텍스트를 코드처럼 취급하세요: 파일에 저장하고, 변경을 검토하고, 어떤 프롬프트 버전이 어떤 자산을 생성했는지 기록하세요. 그러면 "왜 지난 화요일에 이미지가 나빠졌지?"가 답할 수 있는 질문이 됩니다.

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

동작하는 요청은 쉬운 부분일 뿐입니다. 다음 검사가 데모와 통합을 구분합니다.

  • 모든 호출에 타임아웃 설정. 연결 타임아웃과 읽기 타임아웃을 명시적으로 설정하고 기본값을 절대 사용하지 마세요. 읽기 타임아웃이 없는 생성 엔드포인트는 결국 워커를 멈추게 합니다.
  • 상한이 있는 재시도, 재시도 가능한 오류만. 시도 횟수를 제한하고 지터를 추가하며, 유효성 검사 및 인증 실패가 재시도 경로를 완전히 우회하도록 하세요.
  • 키 관리. 키를 환경이나 키 저장소에서 읽고 소스에서 절대 읽지 마세요. 코드 변경 없이 교체할 수 있어야 합니다.
  • 구조화된 로깅. 모델 식별자, 프롬프트(또는 해시와 참조), 설정, HTTP 상태, 시도 횟수, 응답의 모든 요청 식별자를 기록하세요. 이것이 없으면 이미지 문제를 재현할 수 없습니다.
  • 비용 가시성. 생성은 출력 기준으로 과금되므로 사용량은 요청하는 이미지 수와 재시도 빈도에 따라 달라집니다. 요청이 사용자별, 작업별, 백그라운드 실행 중 어느 것인지 미리 정하고 그에 맞게 사용량을 추적하세요—가정을 하드코딩하는 대신 웹사이트의 실시간 가격 패널에서 현재 요금을 확인하세요.
  • 실패 동작 정의. 최종 시도 후 생성이 실패하면 사용자가 무엇을 겪게 될지 결정하세요: 오류 상태, 자리표시자, 또는 대기열 재시도. 정의되지 않은 폴백은 정의되지 않은 사용자 경험이 됩니다.
  • 페이로드 스키마 고정. 의존하는 응답 필드를 저장하고 검증하세요. 그러면 페이로드 변경이 조용한 None이 아니라 명시적 오류로 드러납니다.

최종 검증 단계

curl 명령, Python 함수, 그리고 의도적으로 손상된 요청(먼저 잘못된 키, 다음 잘못된 파라미터)을 실행하여 각각이 예상한 실패를 생성하는지 확인하세요. 이 마지막 단계가 오류 처리가 장식이 아니라 실제임을 알려줍니다.

요청이 인증되고, 이식되고, 합리적으로 재시도되고, 로그에 기록되면 이 통합은 애플리케이션의 나머지 뒤에 둘 수 있습니다.

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

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

API 문서 보기