> ## 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.

# MAI-Image-2.7 이미지 생성

>  - 비동기 처리 모드, 후속 조회를 위해 작업 ID 반환
- 텍스트로 이미지 생성 / 단일 이미지 편집 / 다중 이미지 합성 지원, 참조 이미지 최대 5장
- 고품질 버전 `mai-image-2.7`과 고속 버전 `mai-image-2.7-flash` 제공, 기능과 매개변수는 동일
- `size`(화면비) + `resolution`(`1K` / `2K`)으로 출력 크기 제어, 픽셀 직접 지정도 가능
- 장당 최대 2048×2048(약 419만 픽셀), 요청당 1장 생성 

```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": "mai-image-2.7",
    "prompt": "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명",
    "size": "16:9",
    "resolution": "2K"
  }'
```

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

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "mai-image-2.7",
    "prompt": "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명",
    "size": "16:9",
    "resolution": "2K"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "mai-image-2.7",
  prompt: "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명",
  size: "16:9",
  resolution: "2K"
};

const headers = {
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

```go Go theme={null}
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://api.apimart.ai/v1/images/generations"

    payload := map[string]interface{}{
        "model":      "mai-image-2.7",
        "prompt":     "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명",
        "size":       "16:9",
        "resolution": "2K",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

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

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "파라미터 오류: prompt 가 비어 있음 / size 가 유효하지 않음 / resolution 미지원 / 픽셀 범위 초과 등",
    "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"
  }
}
```

## Authorizations

**Authorization** `string` *required*

모든 엔드포인트는 Bearer Token 인증이 필요합니다

API 키 받기：

[API 키 관리 페이지](https://apimart.ai/keys) 에서 API 키를 받으세요

사용 시 요청 헤더에 다음을 추가：

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required* (default: mai-image-2.7)

이미지 생성 모델 이름

| 모델 | 설명 |
| - | - |
| `mai-image-2.7` | 고품질 버전, 화질을 중시하는 용도에 적합 |
| `mai-image-2.7-flash` | 고속 버전, 화질은 약간 낮지만 더 빠르고 저렴 |

두 모델의 기능과 매개변수는 완전히 동일합니다.

**nsfw\_check** `boolean` (default: false)

이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.

* `true`: `omni-moderation-latest`로 프롬프트와 입력 이미지를 검토
* `false` 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)

**prompt** `string` *required*

이미지 생성을 위한 텍스트 설명 또는 편집 지시

* 중국어와 영어를 지원하며, 자세하게 작성할 것을 권장합니다
* 최대 20,000자, 초과 시 400 반환
* 비어 있거나 공백만으로 구성될 수 없습니다

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

생성할 이미지 수

값: `1`

> [!WARNING]
>
> 요청당 1장만 생성할 수 있습니다. 여러 장이 필요하면 작업을 각각 제출하세요. `0`, 음수 또는 1보다 큰 값을 전달하면 400을 반환합니다

**size** `string` (default: 1:1)

이미지 화면비 또는 픽셀 크기, 텍스트로 이미지 생성 시에만 적용

두 가지 형식을 지원합니다:

* **화면비**: `1:4`부터 `4:1` 범위의 임의의 정수 비율(예: `1:1`, `16:9`, `9:16`, `21:9`). `resolution`과 함께 실제 픽셀을 결정합니다
* **픽셀 크기**: `너비x높이`(`너비*높이`, `너비×높이`도 허용), 예: `2048x1152`. 이 경우 `resolution`은 무시됩니다

픽셀 크기 제약:

* 너비와 높이 모두 **768 이상**
* 너비 × 높이 **4,194,304 이하**(2048×2048)
* 너비와 높이는 각각 32의 배수로 내림됩니다. 예를 들어 `1000x1000`은 실제로 `992x992`로 출력됩니다

예시: ✅ `2048x2048`, `2048x1152`, `2560x1536`; ❌ `512x512`(변 길이가 768 미만), `2080x2048`(총 픽셀 수 초과)

> [!WARNING]
>
> `auto`는 지원하지 않으며, 전달하면 400을 반환합니다

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

출력 해상도 등급, `size`가 화면비일 때만 적용

선택 값: `1K` / `2K`(소문자 허용)

`size × resolution` → 실제 픽셀 대응표:

| size | `1K` | `2K` |
| - | - | - |
| `1:1` | 1024×1024 | 2048×2048 |
| `4:3` | 1152×864 | 2336×1760 |
| `3:4` | 864×1152 | 1760×2336 |
| `3:2` | 1248×832 | 2496×1664 |
| `2:3` | 832×1248 | 1664×2496 |
| `16:9` | 1344×768 | 2720×1536 |
| `9:16` | 768×1344 | 1536×2720 |
| `2:1` | 1536×768 | 2880×1440 |
| `1:2` | 768×1536 | 1440×2880 |
| `21:9` | 1792×768 | 3104×1312 |
| `9:21` | 768×1792 | 1312×3104 |
| `4:1` | 3072×768 | 4096×1024 |
| `1:4` | 768×3072 | 1024×4096 |

> [!WARNING]
>
> `4K`는 지원하지 않으며, 다른 등급을 전달하면 400을 반환합니다. 짧은 변이 최소 768이어야 하므로 2:1보다 더 긴 비율은 `1K` 등급에서도 실제 픽셀이 약 100만을 넘습니다.

**width** `integer`

정확한 픽셀 너비, `height`와 반드시 함께 전달해야 합니다

* 우선순위가 가장 높으며, 함께 전달하면 `size`와 `resolution`을 덮어씁니다
* 제약은 `size` 픽셀 크기와 동일: 너비와 높이 모두 768 이상, 총 픽셀 수 4,194,304 이하
* 텍스트로 이미지 생성 시에만 적용

**height** `integer`

정확한 픽셀 높이, `width`와 반드시 함께 전달해야 하며 제약은 `width`와 동일

**image\_urls** `array`

참조 이미지 배열, 전달하면 이미지로 이미지 생성 모드로 동작합니다

* 1장을 전달하면 단일 이미지 편집, 여러 장을 전달하면 다중 이미지 합성

**세부사항**

* 참조 이미지 최대 5장
* `이미지 URL` 지원(공개적으로 접근 가능한 직접 링크, 접근할 수 없으면 작업이 실패합니다)
* `base64 data URI` 지원(`data:image/png;base64,...` 형식)
* JPEG, PNG 형식 지원, WEBP, GIF는 자동으로 PNG로 변환됩니다
* 출력 크기는 모델이 참조 이미지에 따라 결정하며, `size` / `resolution` / `width` / `height`는 이미지로 이미지 생성에 적용되지 않습니다

**background** `string`

배경 유형

선택 값: `auto` / `opaque`, 전달하지 않은 경우와 결과가 같습니다

> [!WARNING]
>
> 투명 배경 `transparent`는 아직 제공되지 않습니다. `transparent` 또는 기타 값을 전달하면 400을 반환합니다

> [!NOTE]
>
> `auto_aspect_ratio: true`, `web_grounding: true`는 지원하지 않으며, 전달하면 400을 반환합니다. `quality`, `style`, `output_format`, `response_format`, `mask_url`은 지원하지 않으며 무시됩니다. 출력은 PNG로 고정됩니다.

## 사용 시나리오 예시

**텍스트로 이미지 생성(최소 요청)**

기본값은 `1:1` + `1K`이며, 1024×1024를 출력합니다.

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명"
}
```

**텍스트로 이미지 생성(화면비 + 2K 지정)**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "해 질 녘 대학 캠퍼스 포스터, 사실적인 사진 스타일, 영화 같은 조명",
  "size": "3:2",
  "resolution": "2K"
}
```

**텍스트로 이미지 생성(정확한 픽셀)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "흰색 대리석 상판 위의 유리 향수병, 깔끔한 제품 사진",
  "width": 2048,
  "height": 2048
}
```

**단일 이미지 편집**

```json theme={null}
{
  "model": "mai-image-2.7",
  "prompt": "자전거를 파란색으로 바꾸고 옆에 작은 강아지를 추가해 주세요",
  "image_urls": [
    "https://example.com/bicycle.png"
  ]
}
```

**다중 이미지 합성(URL + base64 혼합)**

```json theme={null}
{
  "model": "mai-image-2.7-flash",
  "prompt": "두 참조 이미지를 깔끔하고 미래적인 제품 사진으로 합성해 주세요",
  "image_urls": [
    "https://example.com/first.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
```

## Response

**code** `integer`

응답 상태 코드

**data** `array`

응답 데이터 배열

**속성**

**status** `string`

작업 상태

* `submitted` - 제출됨

**task\_id** `string`

작업 고유 식별자, 후속 결과 조회에 사용

## 작업 결과 조회

제출 성공 후 `task_id` 가 반환됩니다. `GET /v1/tasks/{task_id}` 로 작업 상태를 폴링하세요. 자세한 내용은 [작업 조회 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md) 참조. 3–5초 간격으로 폴링하고 전체 제한 시간은 3분으로 설정하는 것을 권장합니다.

### 성공 응답 예시

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx.png"
          ],
          "expires_at": 1791539365
        }
      ]
    }
  }
}
```

이미지 가져오기: `data.result.images[0].url[0]`. 이미지 링크는 `expires_at` 이후 만료되므로 가능한 한 빨리 다운로드하여 저장하세요.

### 작업 상태

| 상태 | 의미 |
| - | - |
| `pending` | 대기 중, 폴링 계속 |
| `processing` | 생성 중, 폴링 계속 |
| `completed` | 성공, `result.images` 사용 가능 |
| `failed` | 실패, `error.message` 확인 |


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