메인 콘텐츠로 건너뛰기
POST

인증

string
필수
모든 엔드포인트는 Bearer Token 인증을 사용합니다. API 키 페이지에서 키를 발급받으세요.

모델 설명

MiniMax H3 Image는 기본적으로 프롬프트를 상세한 장면 묘사로 자동 확장한 후 이미지를 생성합니다. 확장된 내용은 조회 결과의 revised_prompt에서 확인할 수 있습니다. 원문 그대로 생성하려면 프롬프트 확장 끄기를 참고하세요.
resolution을 생략하면 기본적으로 4K(약 1,600만 픽셀)로 출력되며, 단가는 1K / 2K의 약 3배입니다. 4K가 필요하지 않다면 "resolution": "2K"를 명시적으로 전달하세요.

요청 매개변수

string
필수
이미지 생성 모델 이름입니다. minimax-h3-image로 고정됩니다.
string
필수
이미지 생성 또는 편집을 위한 텍스트 설명입니다.프롬프트는 중국어와 영어를 지원합니다. 앞뒤 공백을 제거한 길이는 1 ~ 32,000자여야 합니다.
string[]
참조 이미지 배열이며 최대 16장입니다. 전달하면 자동으로 편집 모드로 전환됩니다.각 항목은 공개적으로 접근 가능한 http(s):// 직접 링크 또는 data:image/png;base64,... 형식의 인라인 Base64일 수 있습니다(플랫폼이 링크로 변환한 후 모델에 전달합니다).자세한 내용은 참조 이미지 요구 사항을 참고하세요.
string
기본값:"auto"
출력 이미지의 화면 비율 또는 정확한 픽셀 크기입니다.지원 값:
  • auto: 프롬프트에 따라 모델이 구도와 비율을 결정
  • 화면 비율: X:Y 형식이며 X, Y는 1 ~ 300의 정수, 비율은 1:3 ~ 3:1(경계 포함). 예: 1:1, 4:3, 16:9, 9:16, 3:1
  • 정확한 픽셀: 너비x높이 형식. 예: 2048x1152(구분자로 X, ×, *도 사용 가능)
자세한 내용은 크기 규칙을 참고하세요.
string
기본값:"4K"
해상도 등급입니다. 화면 비율과 함께 실제 출력 픽셀을 결정합니다.
  • 1K: 약 100만 픽셀
  • 2K: 약 420만 픽셀
  • 4K(기본값): 약 1,600만 픽셀
소문자로도 입력할 수 있습니다.
size에 정확한 픽셀 형식을 사용할 때는 resolution을 전달할 수 없습니다. 전달하면 400이 반환됩니다.
integer
기본값:"1"
생성할 이미지 수이며 범위는 1 ~ 10입니다.
boolean
기본값:"true"
프롬프트를 자동으로 확장할지 여부입니다.false는 텍스트 기반 이미지 생성에만 적용되며 크기를 명시적으로 지정해야 합니다. 자세한 내용은 프롬프트 확장 끄기를 참고하세요.
string
기본값:"jpeg"
출력 파일 형식입니다.
  • jpeg(기본값, jpg로도 입력 가능)
  • png
  • webp
integer
기본값:"95"
압축 품질이며 범위는 0 ~ 100입니다. png에는 적용되지 않습니다.
boolean
기본값:"false"
이미지에 눈에 보이는 AI 생성 워터마크를 추가할지 여부입니다. 이미지 메타데이터의 비가시적 식별 정보에는 영향을 주지 않습니다.
다음 매개변수는 지원되지 않으며 전달해도 무시됩니다: quality, style, seed, negative_prompt, background, mask_url.결과는 항상 URL로 반환되며, response_format: "b64_json"을 전달하면 400이 반환됩니다.

크기 규칙

해상도 등급 + 화면 비율

해상도 등급은 전체 면적을, 화면 비율은 형태를 결정합니다: 실제 출력 픽셀은 비율과 등급에 따라 모델이 반올림하여 결정하므로 반환 결과를 기준으로 하세요. 정확한 크기가 필요하면 픽셀 형식을 사용하세요.

정확한 픽셀

size: "너비x높이"를 사용할 때는 다음 조건을 충족해야 합니다:
  • ✅ 1024x1024, 2048x1152, 1536x1536, 4000x5000
  • ❌ 512x512(면적이 너무 작음), 4000x1000(비율이 3:1 초과), 5000x5000(2,000만 픽셀 초과)

참조 이미지 요구 사항

URL을 사용할 때는 링크가 공개적으로 접근 가능한지 확인하세요. 링크에 접근할 수 없으면 작업이 생성 단계에서 실패합니다(status가 failed가 되며 비용은 전액 환불됩니다).편집 모드에서는 프롬프트 확장이 항상 켜져 있으며 끌 수 없습니다.

프롬프트 확장 끄기

기본적으로 모델은 프롬프트를 확장한 후 이미지를 생성합니다. 원문 그대로 생성하려면 "prompt_optimizer": false를 전달할 수 있으며, 다음 조건을 충족해야 합니다:
  • 텍스트 기반 이미지 생성에만 사용할 수 있으며, image_urls가 포함되면 400이 반환됩니다
  • 크기를 명시적으로 지정해야 합니다: size는 화면 비율(예: 1:1) 또는 픽셀(예: 1024x1024)이어야 하며 auto이거나 생략할 수 없습니다
끄면 모델은 프롬프트의 앞부분 약 4096개 토큰만 읽습니다.

Response

integer
응답 상태 코드이며, 제출에 성공하면 200입니다.
array
제출 응답 데이터입니다.

제출 응답

제출에 성공하면 비동기 작업 ID가 즉시 반환됩니다:

작업 결과 조회

제출 응답의 task_id로 작업 상태 API를 호출하세요:
실측 기준으로 1K / 2K 이미지 한 장은 약 10 ~ 20초, 4K는 약 20초, 참조 이미지 편집은 약 20초가 걸립니다. 상태가 completed 또는 failed가 될 때까지 3 ~ 5초마다 폴링하세요. 단일 작업은 최대 600초까지 실행될 수 있으므로 클라이언트 폴링 타임아웃은 10분으로 설정하는 것을 권장합니다.

작업 성공

이미지 URL은 data.result.images[0].url[]에 있으며, n장의 이미지가 모두 이 배열에 포함됩니다. expires_at 이전에 다운로드하여 저장하세요. 작업이 실패하면 status가 failed가 되고 원인은 error.message에서 확인할 수 있으며, 비용은 자동으로 전액 환불됩니다.

사용 예시

텍스트 기반 이미지 생성(기본 4K)

텍스트 기반 이미지 생성(1K + 화면 비율, 한 번에 4장)

정확한 픽셀 + PNG

참조 이미지 편집

프롬프트 확장 끄기