> ## 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`）で出力サイズを制御、ピクセルの直接指定も可能
- 1 枚あたり最大 2048×2048（約 419 万ピクセル）、1 回につき 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 回につき 1 枚のみ生成できます。複数枚が必要な場合は個別にタスクを送信してください。`0`、負の数、または 1 より大きい値を指定すると 400 を返します

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

画像のアスペクト比またはピクセルサイズ。テキストから画像生成の場合のみ有効

2 つの指定方法に対応します：

* **アスペクト比**：`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": "2 枚の参照画像を合成して、すっきりした未来的な商品写真にしてください",
  "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/ja/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.