> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax-H3-Image-Highspeed 이미지 생성

>  - minimax-h3-image-highspeed 고속 모델 사용, 더 빠른 생성 속도, 매개변수는 표준 버전과 완전히 동일
- 비동기 처리 방식으로 task_id를 반환하여 이후 결과 조회에 사용
- 텍스트 기반 이미지 생성과 최대 16장의 참조 이미지를 사용한 편집 지원
- 요청당 최대 10장 생성, 프롬프트 확장 기본 제공(끌 수 있음)
- 1K / 2K / 4K 해상도와 화면 비율 조합 또는 픽셀 크기 직접 지정 지원(최대 2,000만 픽셀) 

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "minimax-h3-image-highspeed",
    "prompt": "해 질 녘 바닷가 카페, 사실적인 사진 스타일, 따뜻한 색감",
    "size": "16:9",
    "resolution": "2K",
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "minimax-h3-image-highspeed",
        "prompt": "해 질 녘 바닷가 카페, 사실적인 사진 스타일, 따뜻한 색감",
        "size": "16:9",
        "resolution": "2K",
        "n": 1,
    },
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.apimart.ai/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "minimax-h3-image-highspeed",
      prompt: "해 질 녘 바닷가 카페, 사실적인 사진 스타일, 따뜻한 색감",
      size: "16:9",
      resolution: "2K",
      n: 1,
    }),
  },
);

console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "잘못된 요청 매개변수",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "인증에 실패했습니다. API 키를 확인하세요.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "계정 잔액이 부족합니다",
    "type": "payment_required"
  }
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "message": "요청이 너무 많습니다. 잠시 후 다시 시도하세요.",
    "type": "rate_limit_error"
  }
}
```

```json 500 theme={null}
{
  "error": {
    "code": 500,
    "message": "서버 내부 오류가 발생했습니다. 잠시 후 다시 시도하세요.",
    "type": "server_error"
  }
}
```

## 인증

**Authorization** `string` *required*

모든 엔드포인트는 Bearer Token 인증을 사용합니다. [API 키 페이지](https://apimart.ai/keys)에서 키를 발급받으세요.

```
Authorization: Bearer YOUR_API_KEY
```

## 모델 설명

| 모델 | 특징 | 권장 용도 |
| - | - | - |
| `minimax-h3-image-highspeed` | 고속 버전, 더 빠른 생성, 이미지 입력 / 출력 단가는 표준 버전의 2배 | 응답 속도가 중요한 시나리오, 인터랙티브 이미지 생성 |
| `minimax-h3-image` | 표준 버전, 더 낮은 단가 | 대량 생성. 자세한 내용은 [MiniMax-H3-Image](https://docs.apimart.ai/ko/api-reference/images/minimax-h3-image/generation.md) 참고 |

MiniMax H3 Image는 사실적인 사진, 포스터, 제품 이미지, 텍스트가 포함된 이미지에 강점이 있습니다. 기본적으로 프롬프트를 상세한 장면 묘사로 자동 확장한 후 이미지를 생성하며, 확장된 내용은 조회 결과의 `revised_prompt`에서 확인할 수 있습니다. 원문 그대로 생성하려면 [프롬프트 확장 끄기](#프롬프트-확장-끄기)를 참고하세요.

> [!WARNING]
>
> `resolution`을 생략하면 기본적으로 **4K**(약 1,600만 픽셀)로 출력되며, 단가는 1K / 2K의 약 3.6배입니다. 4K가 필요하지 않다면 `"resolution": "2K"`를 명시적으로 전달하세요.

## 요청 매개변수

**model** `string` *required*

이미지 생성 모델 이름입니다. `minimax-h3-image-highspeed`로 고정됩니다.

**prompt** `string` *required*

이미지 생성 또는 편집을 위한 텍스트 설명입니다.

프롬프트는 중국어와 영어를 지원합니다. 앞뒤 공백을 제거한 길이는 `1` \~ `32,000`자여야 합니다.

**image\_urls** `string[]`

참조 이미지 배열이며 최대 `16`장입니다. 전달하면 자동으로 편집 모드로 전환됩니다.

각 항목은 공개적으로 접근 가능한 `http(s)://` 직접 링크 또는 `data:image/png;base64,...` 형식의 인라인 Base64일 수 있습니다(플랫폼이 링크로 변환한 후 모델에 전달합니다).

자세한 내용은 [참조 이미지 요구 사항](#참조-이미지-요구-사항)을 참고하세요.

**size** `string` (default: 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`, `×`, `*`도 사용 가능)

자세한 내용은 [크기 규칙](#크기-규칙)을 참고하세요.

**resolution** `string` (default: 4K)

해상도 등급입니다. 화면 비율과 함께 실제 출력 픽셀을 결정합니다.

* `1K`: 약 100만 픽셀
* `2K`: 약 420만 픽셀
* `4K`(기본값): 약 1,600만 픽셀

소문자로도 입력할 수 있습니다.

> [!WARNING]
>
> `size`에 정확한 픽셀 형식을 사용할 때는 `resolution`을 **전달할 수 없습니다**. 전달하면 400이 반환됩니다.

**n** `integer` (default: 1)

생성할 이미지 수이며 범위는 `1` \~ `10`입니다.

**prompt\_optimizer** `boolean` (default: true)

프롬프트를 자동으로 확장할지 여부입니다.

`false`는 텍스트 기반 이미지 생성에만 적용되며 크기를 명시적으로 지정해야 합니다. 자세한 내용은 [프롬프트 확장 끄기](#프롬프트-확장-끄기)를 참고하세요.

**output\_format** `string` (default: jpeg)

출력 파일 형식입니다.

* `jpeg`(기본값, `jpg`로도 입력 가능)
* `png`
* `webp`

**output\_compression** `integer` (default: 95)

압축 품질이며 범위는 `0` \~ `100`입니다. `png`에는 적용되지 않습니다.

**watermark** `boolean` (default: false)

이미지에 눈에 보이는 AI 생성 워터마크를 추가할지 여부입니다. 이미지 메타데이터의 비가시적 식별 정보에는 영향을 주지 않습니다.

> [!NOTE]
>
> 다음 매개변수는 지원되지 않으며 전달해도 무시됩니다: `quality`, `style`, `seed`, `negative_prompt`, `background`, `mask_url`.
>
> 결과는 항상 URL로 반환되며, `response_format: "b64_json"`을 전달하면 400이 반환됩니다.

## 크기 규칙

| 원하는 결과 | 전달 방법 |
| - | - |
| 기본값(4K, 모델이 비율 선택) | 크기 관련 매개변수 생략 |
| 해상도 등급 + 화면 비율 | `size: "16:9"`, `resolution: "2K"` |
| 해상도 등급만 지정하고 비율은 모델이 결정 | `resolution: "1K"`(`size` 생략 또는 `auto`) |
| 픽셀 단위로 정확히 지정 | `size: "2048x1152"`(**`resolution`은 함께 전달하지 않음**) |

### 해상도 등급 + 화면 비율

해상도 등급은 전체 면적을, 화면 비율은 형태를 결정합니다:

| 등급 | 목표 면적 | 실측 출력 예시 |
| - | - | - |
| `1K` | 약 1024×1024(약 100만 픽셀) | 모델 선택 비율 → 1184×880 |
| `2K` | 약 2048×2048(약 420만 픽셀) | `1:1` → 2048×2048 |
| `4K`(기본값) | 약 4096×4096(약 1,600만 픽셀) | 모델 선택 비율 → 3552×4736 |

실제 출력 픽셀은 비율과 등급에 따라 모델이 반올림하여 결정하므로 반환 결과를 기준으로 하세요. 정확한 크기가 필요하면 픽셀 형식을 사용하세요.

### 정확한 픽셀

`size: "너비x높이"`를 사용할 때는 다음 조건을 충족해야 합니다:

| 제약 | 값 |
| - | - |
| 총 픽셀(너비 × 높이) | `655,360` \~ `20,000,000` |
| 화면 비율 | `1:3` \~ `3:1` |
| `resolution`과의 관계 | 함께 전달할 수 없음 |

* ✅ `1024x1024`, `2048x1152`, `1536x1536`, `4000x5000`
* ❌ `512x512`(면적이 너무 작음), `4000x1000`(비율이 3:1 초과), `5000x5000`(2,000만 픽셀 초과)

## 참조 이미지 요구 사항

| 항목 | 요구 사항 |
| - | - |
| 개수 | 최대 16장 |
| 형식 | JPG / JPEG / PNG / WebP / HEIC / HEIF(GIF 미지원) |
| 파일 크기 | 장당 64 MB 이하 |
| 이미지 크기 | 각 변 128 \~ 8192픽셀, 긴 변 ÷ 짧은 변 ≤ 4 |

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

## 프롬프트 확장 끄기

기본적으로 모델은 프롬프트를 확장한 후 이미지를 생성합니다. 원문 그대로 생성하려면 `"prompt_optimizer": false`를 전달할 수 있으며, 다음 조건을 충족해야 합니다:

* **텍스트 기반 이미지 생성**에만 사용할 수 있으며, `image_urls`가 포함되면 400이 반환됩니다
* **크기를 명시적으로 지정**해야 합니다: `size`는 화면 비율(예: `1:1`) 또는 픽셀(예: `1024x1024`)이어야 하며 `auto`이거나 생략할 수 없습니다

끄면 모델은 프롬프트의 앞부분 약 4096개 토큰만 읽습니다.

## Response

**code** `integer`

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

**data** `array`

제출 응답 데이터입니다.

**배열 항목**

**status** `string`

초기 상태는 `submitted`입니다.

**task\_id** `string`

작업의 고유 식별자이며, 작업 상태와 생성 결과를 조회하는 데 사용합니다.

## 제출 응답

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

```json theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## 작업 결과 조회

제출 응답의 `task_id`로 [작업 상태 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 호출하세요:

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

고속 버전은 표준 버전보다 빠르게 이미지를 생성합니다(표준 버전 실측 기준 1K / 2K 이미지 한 장은 약 10 \~ 20초, 4K는 약 20초). 상태가 `completed` 또는 `failed`가 될 때까지 3 \~ 5초마다 폴링하세요. 단일 작업은 최대 600초까지 실행될 수 있으므로 클라이언트 폴링 타임아웃은 10분으로 설정하는 것을 권장합니다.

### 작업 성공

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "created": 1794450409,
    "completed": 1794450428,
    "actual_time": 19,
    "estimated_time": 60,
    "cost": 0.0493,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example_0.jpeg",
            "https://upload.apimart.ai/f/image/example_1.jpeg"
          ],
          "expires_at": 1794536828,
          "revised_prompt": "The image is a realistic, close-up still life photograph of ...",
          "revised_prompts": [
            "The image is a realistic ...",
            "The image is a professional ..."
          ]
        }
      ]
    }
  }
}
```

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

## 사용 예시

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

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "A cozy coffee shop by the sea at sunset, photorealistic, warm tones"
}
```

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

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "미니멀한 스타일의 헤드폰 제품 이미지, 흰색 배경, 부드러운 그림자",
  "size": "1:1",
  "resolution": "1K",
  "n": 4
}
```

### 정확한 픽셀 + PNG

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "도시 야경 포스터, 네온사인, 사이버펑크 스타일, 제목 텍스트 NIGHT CITY",
  "size": "2048x1152",
  "output_format": "png"
}
```

### 참조 이미지 편집

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "첫 번째 이미지의 인물에게 두 번째 이미지의 재킷을 입히고 배경은 그대로 유지",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/jacket.png"
  ],
  "resolution": "2K"
}
```

### 프롬프트 확장 끄기

```json theme={null}
{
  "model": "minimax-h3-image-highspeed",
  "prompt": "a red apple on a wooden table, top view",
  "size": "1:1",
  "resolution": "1K",
  "prompt_optimizer": false
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.