MiniMax H3-Image API로 이미지 생성하고 편집하는 방법

MiniMax H3-Image API는 두 개의 REST 엔드포인트로 이미지를 생성하고 편집합니다. 텍스트-이미지 변환에는 POST /v1/images/generations, 1~16장의 참조 이미지로 편집할 때는 POST /v1/images/edits를 사용합니다. Bearer 키, 모델 ID MiniMax-H3-Image(또는 MiniMax-H3-Image-Highspeed), 프롬프트, 크기를 보내면 이미지 URL 또는 base64 데이터를 받게 됩니다. 이 API는 MiniMax M3 API와 동일한 MiniMax 개발자 플랫폼에서 제공됩니다. 출력은 업스케일러 없이도 약 16메가픽셀까지 지원합니다.

아래에서는 API 키, 중요한 파라미터, 이미지 편집, 출시 할인이 적용된 가격, 그리고 Apidog CLI를 활용한 에이전트 기반 테스트를 다룹니다. 이 모델이 처음이라면 MiniMax H3-Image란 무엇인가부터 시작하세요.

MiniMax H3-Image API란?

MiniMax H3-Image API는 MiniMax의 오픈 웨이트(open-weight) 모델인 H3-Image를 호스팅하는 엔드포인트로, 하나의 체크포인트에서 텍스트-이미지 생성과 다중 참조 이미지 편집을 모두 처리합니다. https://api.minimax.io에서 제공되며, JSON 요청을 받고 OpenAI SDK의 images.generate 및 images.edit 호출과 호환되므로, 기존 이미지 코드는 base URL과 모델 이름만 바꾸면 대부분 그대로 사용할 수 있습니다.

웨이트(weights)도 공개되어 있습니다. Hugging Face 모델 카드에 따르면 MiniMax-H3-Image Community License 하에 33.1B 파라미터의 diffusion transformer가 공개되어 있습니다. 셀프 호스팅에는 체크포인트 약 69GB와 66.7GB 규모의 텍스트 인코더가 필요하므로, 대부분의 팀에게는 API가 실용적인 선택입니다.

2026-11-11 기준 MiniMax의 API 레퍼런스에 나온 호스팅 측 정보는 다음과 같습니다:

MiniMax API 키 발급하기

1. MiniMax 개발자 플랫폼에 로그인합니다.
2. Account Management를 연 뒤 API Keys로 이동하여 키를 생성합니다.
3. 잔액을 충전합니다. 잔액이 없는 상태로 요청하면 HTTP 402와 오류 코드 1008(잔액 부족)가 반환됩니다.
4. 키를 환경 변수로 내보내 코드와 에이전트가 커밋하는 파일이 아닌 환경에서 키를 읽도록 합니다:

export MINIMAX_API_KEY="your-key-here"

모든 호출에서 이 키는 Authorization: Bearer $MINIMAX_API_KEY 형태로 전송됩니다.

첫 번째 텍스트-이미지 생성 요청

가장 간단한 호출에는 model, prompt와 크기 또는 area 티어 중 하나가 필요합니다:

curl https://api.minimax.io/v1/images/generations \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "MiniMax-H3-Image",
    "prompt": "An orange cat lying on a windowsill basking in the sun, warm afternoon light, film texture",
    "aspect_ratio": "16:9",
    "area": "2K",
    "n": 1,
    "response_format": "url"
  }'

OpenAI Python SDK를 사용할 경우 base_url을 MiniMax로 지정하고 재시도를 비활성화하세요:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.io/v1",
    api_key=os.environ["MINIMAX_API_KEY"],
    timeout=600,
    max_retries=0,
)

result = client.images.generate(
    model="MiniMax-H3-Image",
    prompt="An orange cat lying on a windowsill basking in the sun, warm afternoon light",
    size="2720x1536",
    response_format="url",
)
for item in result.data:
    print(item.url)  # 실패한 이미지는 None

max_retries=0 설정이 중요합니다. 이 엔드포인트는 멱등(idempotent)하지 않습니다. 클라이언트 타임아웃이 발생해도 서버는 작업을 완료하고 비용을 청구하므로, 자동 재시도 시 비용이 이중으로 청구될 수 있습니다. 대신 타임아웃을 600초로 설정하세요.

중요한 요청 파라미터

출력 크기는 두 가지 방식 중 하나로만 제어할 수 있으며, 두 방식을 섞어 쓸 수는 없습니다.

정확한 픽셀 지정. size를 WIDTHxHEIGHT 형태로 설정합니다(예: 4096x4096). 전체 면적은 655,360픽셀 이상 20,000,000픽셀 이하, 가로세로 비율은 1:3에서 3:1 사이여야 합니다. 이 모드에서는 aspect_ratio나 area를 auto로 보내는 것조차 전송하면 안 되며, 그렇지 않으면 400 오류가 발생합니다.

티어 + 비율. size는 auto로 두고 area(1K, 2K, 4K, 기본값 4K)와 aspect_ratio(1:3~3:1 범위의 X:Y)를 설정합니다. 서버가 픽셀을 계산하며, 16:9 비율의 2K는 2720 x 1536을 반환합니다.

나머지 필드는 다음과 같습니다:

사람들이 놓치기 쉬운 규칙 두 가지가 있습니다. 첫째, 프롬프트 개선 기능을 끄면 정확한 size 또는 명시적인 aspect_ratio를 지정해야 하며, auto를 보내면 400 오류가 발생합니다. 둘째, b64_json은 총 출력 면적에 제한이 있습니다: PNG는 20,000,000픽셀(모든 크기의 이미지 1장), JPEG 또는 WebP는 80,000,000픽셀(4K 이미지 4장 또는 2K 이미지 10장)입니다. 더 큰 배치 작업에는 URL을 사용하세요.

모델 카드에 따르면 H3-Image는 약 16MP에서 최상의 성능을 발휘합니다: 4096x4096(1:1), 5472x3072(16:9), 6272x2688(21:9).

최대 16장의 참조 이미지로 이미지 편집하기

편집은 동일한 필드에 images 배열을 더해 사용합니다. 프롬프트에서 입력 이미지는 위치("image 1", "image 2")로 참조합니다:

import os, requests

resp = requests.post(
    "https://api.minimax.io/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['MINIMAX_API_KEY']}"},
    json={
        "model": "MiniMax-H3-Image",
        "prompt": "Replace the cat in image 1 with the Shiba Inu in image 2, keep the background unchanged",
        "images": [
            {"image_url": "https://example.com/cat.jpg"},
            {"image_url": "https://example.com/dog.png"},
        ],
        "size": "auto",
        "response_format": "url",
    },
    timeout=600,
)
resp.raise_for_status()
print(resp.json()["data"])

이 엔드포인트는 multipart/form-data도 지원하며, OpenAI SDK의 images.edit이 파일을 업로드할 때 사용하는 방식이 바로 이것입니다. edits 레퍼런스의 제한 사항:

• JPG, PNG, WebP, HEIC 또는 HEIF 형식의 이미지 1~16장
• 각 변은 128~8,192픽셀, 장변과 단변의 비율은 4:1 이하
• 전체 요청 본문 최대 64MiB; base64는 약 1/3 크기가 늘어나므로 큰 입력에는 공개 URL 사용

응답 읽기 및 오류 처리

성공한 호출은 요청한 이미지마다 하나의 data 항목을 순서대로 반환합니다:

{
  "data": [
    {"url": "https://.../output-0.jpg", "size": "2720x1536", "revised_prompt": "Warm afternoon light streams through..."},
    {"error": {"code": "1027", "message": "output image failed content safety check"}}
  ],
  "output_format": "jpeg",
  "usage": {"generated_images": 1, "input_tokens": 3174, "output_tokens": 4080, "total_tokens": 7254},
  "request_id": "0217..."
}

통합 작업의 신뢰성을 지키는 세 가지 습관:

1. 모든 항목에서 error를 확인하세요. 최소 한 장의 이미지가 성공하면 HTTP 상태는 200이므로, 200이라고 해서 요청한 n장이 모두 반환된 것은 아닙니다. 모든 이미지가 실패하면 402, 422 또는 500이 반환됩니다.
2. URL을 즉시 다운로드하세요. MiniMax는 URL의 지속적인 가용성을 보장하지 않으므로, 파일을 자체 스토리지로 복사하세요.
3. request_id를 기록하세요. 지원팀이 문의하는 추적 ID입니다.

속도 제한은 429를 반환합니다. 코드 1002는 분당 이미지 수 한도를 초과했다는 의미이며, 각 요청은 n장의 이미지로 계산되므로 10장 배치는 할당량 중 10을 한 번에 사용합니다.

MiniMax H3-Image 가격 및 출시 할인

과금은 토큰 단위이며, 성공한 이미지에만 비용이 청구됩니다. 2026-11-11에 확인한 MiniMax의 가격 페이지 기준:

MiniMax는 표준 모델의 이미지당 예상 비용 예시도 공개하고 있습니다:

Highspeed는 이미지당 약 1.6~2배 비용이 듭니다(4K 기준 $0.13001, 할인 시 $0.06501). 프롬프트 길이에 따라 입력 비용이 달라지므로 이 수치는 참고용으로 보세요.

출시 프로모션: 2026년 11월 17일 16:00 UTC까지, 전달된 이미지가 최소 16,600,000픽셀 이상이면 MiniMax가 두 모델 모두의 요청 총비용에서 50%를 할인합니다. 4096x4096 이미지(16,777,216픽셀)는 대상이지만 2K 이미지는 대상이 아닙니다. 무료로 사용하는 방법을 찾고 계신가요? MiniMax H3-Image 무료로 사용하는 방법을 참고하세요.

Apidog CLI로 코딩 에이전트에게 테스트시키기

이미지 API는 조용히 실패합니다: 200을 반환했는데 이미지 절반이 빠져 있거나, 잊고 있던 크기 규칙이 문제를 일으키는 식이죠. 응답을 일일이 검사하는 대신, 코딩 에이전트(Claude Code, Codex, Cursor)가 Apidog CLI로 반복 가능한 테스트를 만들도록 하세요.

한 번만 설정하세요:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

그다음 에이전트에게 프롬프트 하나를 주세요:

In Apidog project <projectId>, create an environment "MiniMax Global" with base URL
https://api.minimax.io. Add the endpoint POST /v1/images/generations from the MiniMax
H3-Image API reference, with Bearer auth from the {{MINIMAX_API_KEY}} variable.
Create a test case that sends model MiniMax-H3-Image, area 1K, aspect_ratio 1:1, n 1,
and asserts HTTP 200, data[0].url exists, and no item in data has an error field.
Run it and summarize any failures.

에이전트는 각 페이로드 스키마를 읽고 JSON을 검증한 뒤, 리소스를 생성하고 케이스를 실행합니다:

apidog environment create "MiniMax Global" --project <projectId> --base-url https://api.minimax.io
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "MINIMAX_API_KEY=$MINIMAX_API_KEY" -r cli,json

--env-var는 실행 시점에 키를 전달하므로 키가 저장된 파일에 남지 않습니다. cli 리포터는 각 assertion을 통과/실패로 출력하고, json은 에이전트가 다시 읽을 수 있는 보고서를 작성합니다. 테스트는 1K로 유지하세요. 실행할 때마다 실제로 과금되는 생성이 발생합니다. 동일한 명령은 -r junit으로 CI에서도 실행할 수 있습니다(Apidog CLI CI/CD 가이드와 Claude Code에서 Apidog CLI 사용하기 참고). Apidog의 Free 플랜은 최대 4명까지 사용할 수 있습니다.

Standard vs Highspeed: 어떤 모델 ID를 쓸까?

두 ID는 동일한 파라미터를 사용하므로 전환은 문자열 하나만 바꾸면 됩니다. 최종 자산과 비용에 민감한 배치 작업에는 MiniMax-H3-Image를, 지연 시간이 가격보다 중요한 인터랙티브 미리보기에는 MiniMax-H3-Image-Highspeed를 사용하세요. API 레퍼런스에는 지연 시간 수치가 없으므로 직접 프롬프트로 시간을 측정해 보세요. 대안을 검토 중이라면 MiniMax H3-Image vs Nano Banana 2.1, Nano Banana 2.1 API 가이드, 또는 GPT Image 2.6 API 가이드를 참고하세요.

FAQ

MiniMax H3-Image의 모델 ID는 무엇인가요? 표준 모델은 MiniMax-H3-Image, 더 빠르고 비싼 버전은 MiniMax-H3-Image-Highspeed를 사용하세요. 두 모델 모두 동일한 파라미터로 /v1/images/generations와 /v1/images/edits에서 작동합니다.

MiniMax H3-Image API는 OpenAI SDK와 호환되나요? 네. base_url="https://api.minimax.io/v1"을 설정하고 images.generate 또는 images.edit를 호출하면 됩니다. 재시도는 새로운 과금 생성을 유발하므로 max_retries=0으로 설정하세요.

편집에 사용할 수 있는 참조 이미지는 몇 장인가요? 요청당 1~16장까지 가능하며, 각 이미지는 한 변 128~8,192픽셀이고 전체 요청 본문은 64MiB 미만이어야 합니다.

MiniMax H3-Image 이미지 한 장의 비용은 얼마인가요? MiniMax의 예시에 따르면 표준 텍스트-이미지 생성은 1K 기준 약 $0.022, 4K 기준 약 $0.069이며, 2026년 11월 17일 16:00 UTC까지는 4K가 절반인 약 $0.034로 할인됩니다.

200을 받았는데 요청한 것보다 이미지가 적게 온 이유는? 부분 성공은 200을 반환합니다. 안전 검사에 걸린 항목을 포함해 실패한 항목은 url 대신 error 객체를 담고 있으며, 해당 항목에 대해서는 비용이 청구되지 않습니다.