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

# Flux Kontext 画像生成

>  - 非同期処理モード。後続の照会に使用するタスク ID を返します
- Pro と Max はどちらもテキストからの画像生成と参照画像の編集に対応しています
- 生成結果の expires_at は画像リンクの有効期限を示します 

<RequestExample>
  ```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": "flux-kontext-pro",
      "prompt": "髪の色を青に変える",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
    }'
  ```

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

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

  payload = {
      "model": "flux-kontext-pro",
      "prompt": "髪の色を青に変える",
      "image_urls": ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
      "size": "16:9"
  }

  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: "flux-kontext-pro",
    prompt: "髪の色を青に変える",
    image_urls: ["https://upload.apimart.ai/f/models/9998230420418352-159728fe-5ae8-4330-857a-a84c034d8d21-flux-kontext-pro.webp"],
    size: "16:9"
  };

  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));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "認証に失敗しました。APIキーを確認してください",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "残高が不足しています。チャージしてから再試行してください",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## 対応モデル

| モデル名               | 説明                             |
| ------------------ | ------------------------------ |
| `flux-kontext-pro` | Flux Kontext Pro 画像生成・編集モデル    |
| `flux-kontext-max` | Flux Kontext Max 高品質画像生成・編集モデル |

## 認証

<ParamField header="Authorization" type="string" required>
  すべてのエンドポイントで Bearer Token による認証が必要です

  API Key の取得：

  [API Key 管理ページ](https://apimart.ai/keys)で API Key を取得してください

  リクエストヘッダーに次の値を追加します：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  モデル名

  * `flux-kontext-pro` - Kontext Pro 画像生成・編集モデル
  * `flux-kontext-max` - Kontext Max 高品質画像生成・編集モデル
</ParamField>

<ParamField body="prompt" type="string" required>
  画像の生成または編集内容を記述するテキスト。
</ParamField>

<ParamField body="image_urls" type="array">
  参照画像のリスト。省略するとテキストから画像を生成し、指定すると画像を編集します。

  **制限：**

  * 最大 4 枚の画像に対応
  * 公開アクセス可能な URL または Base64 エンコードされた入力画像に対応しています
  * 出力画像とすべての参照画像の合計ピクセル数は 9MP 以下でなければなりません
</ParamField>

<ParamField body="size" type="string" default="1:1">
  画像のアスペクト比

  対応するアスペクト比：

  * `1:1` - 正方形（デフォルト）
  * `4:3` - 横向き 4:3
  * `3:4` - 縦向き 3:4
  * `16:9` - 横向きワイドスクリーン
  * `9:16` - 縦向き
  * `3:2` - 横向き 3:2
  * `2:3` - 縦向き 2:3
  * `21:9` - ウルトラワイド
  * `9:21` - ウルトラトール

  `1024x1536` のようなピクセル文字列は、対応する最も近いアスペクト比にマッピングされ、正確なピクセルサイズでは出力されません。Kontext は `width` と `height` に対応しておらず、指定するとタスクが失敗します。`resolution` は Kontext では効果がなく、出力は約 1MP です。
</ParamField>

<ParamField body="output_format" type="string" default="png">
  出力画像のエンコード形式

  * `png` - PNG 形式（デフォルト）
  * `jpeg` - JPEG 形式
  * `webp` - WebP 形式
</ParamField>

<ParamField body="response_format" type="string">
  レスポンス形式の互換パラメータ。指定できる値は `url` と `b64_json` です。画像のエンコード形式は変わらず、画像形式には `output_format` が優先して使用されます。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成する画像の枚数。値は `1` でなければなりません。複数枚が必要な場合は、複数のタスクを送信してください。
</ParamField>

<ParamField body="seed" type="integer">
  ランダムシード。同じシードとその他のパラメータを使用すると、同じ結果を再現できます。省略した場合はランダムに生成されます。
</ParamField>

<ParamField body="prompt_upsampling" type="boolean" default="false">
  プロンプト強化を有効にするかどうか

  * `true` - 有効
  * `false` - 無効（デフォルト）

  > 明示的に `false` を設定すると、プロンプトの書き換えを無効にできます。
</ParamField>

<ParamField body="safety_tolerance" type="integer" default="2">
  セーフティ許容度

  範囲：0～6。値が大きいほど許容度が高くなります
</ParamField>

### 実際の出力サイズ

| 比率     | 実際の出力サイズ  |
| ------ | --------- |
| `1:1`  | 1024×1024 |
| `4:3`  | 1184×880  |
| `3:4`  | 880×1184  |
| `16:9` | 1392×752  |
| `9:16` | 752×1392  |
| `3:2`  | 1248×832  |
| `2:3`  | 832×1248  |
| `21:9` | 1568×672  |
| `9:21` | 672×1568  |

## ユースケース例

**画像編集（入力画像あり）**

```json theme={null}
{
    "model": "flux-kontext-pro",
    "prompt": "背景をビーチに変更",
    "image_urls": ["https://example.com/photo.jpg"],
    "size": "16:9",
    "output_format": "png"
}
```

**テキストから画像を生成（入力画像なし）**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "青い猫",
    "size": "1:1",
    "seed": 12345
}
```

**複数の参照画像を使った編集**

```json theme={null}
{
    "model": "flux-kontext-max",
    "prompt": "画像 1 の人物を画像 2 のシーンに配置し、ライティングを統一する",
    "image_urls": [
        "https://example.com/person.jpg",
        "https://example.com/scene.jpg"
    ],
    "size": "4:3"
}
```

## Response

<ResponseField name="code" type="integer">
  レスポンスステータスコード
</ResponseField>

<ResponseField name="data" type="array">
  レスポンスデータの配列

  <Expandable title="属性">
    <ResponseField name="status" type="string">
      タスクステータス

      * `submitted` - 送信済み
    </ResponseField>

    <ResponseField name="task_id" type="string">
      タスクの一意の識別子。後続のタスク結果の照会に使用します
    </ResponseField>
  </Expandable>
</ResponseField>

## タスク結果の照会

送信に成功したら、`GET /v1/tasks/{task_id}` でタスクのステータスをポーリングします。詳しくは[タスク照会 API](/ja/api-reference/tasks/status)を参照してください。

### 成功レスポンス例

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "created": 1785133674,
    "completed": 1785133683,
    "actual_time": 9,
    "estimated_time": 15,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"
          ],
          "expires_at": 1785220083
        }
      ]
    }
  }
}
```

画像の取得パスは `data.result.images[0].url[0]` です。`expires_at` はこのリンクの有効期限を表す Unix タイムスタンプです。有効期限までに画像を保存してください。

### タスクステータス

| ステータス                   | 意味                                  |
| ----------------------- | ----------------------------------- |
| `submitted` / `pending` | 受付済みまたは処理待ち。ポーリングを続けます              |
| `processing`            | 生成中。ポーリングを続けます                      |
| `completed`             | 生成成功。結果は `result.images` にあります      |
| `failed`                | 生成失敗。`data.error.message` を確認してください |

### 無効なモデルパラメータとタスクの失敗

無効なモデルパラメータは非同期で通知されます。送信時は HTTP 200 と `task_id` が返り、タスクを照会すると最終的に `failed` となり、具体的な理由が `data.error.message` に示されます。そのため、必ず最終ステータスまでポーリングしてください。

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}
```

この種のエラーでは `data.error.code` は常に `task_failed` で、具体的な理由は `message` に記載されます。失敗したタスクは全額返金されます。

## 注意事項

1. **非同期処理**：送信後に `task_id` が返されます。結果を取得するには `/v1/tasks/{task_id}` をポーリングしてください。
2. **参照画像の要件**：参照画像は最大 4 件まで指定でき、公開アクセス可能な画像 URL または Base64 エンコードされた入力画像を使用できます。出力画像との合計は 9MP 以下でなければなりません。
3. **サイズのルール**：デフォルトのアスペクト比は `1:1` です。ピクセル文字列は最も近い対応比率にマッピングされ、`width`/`height` は拒否され、`resolution` は効果がありません。Kontext の出力は約 1MP です。
4. **生成枚数**：`n` は `1` でなければならず、1 回のリクエストで生成される画像は 1 枚です。
5. **プロンプトの書き換え**：`prompt_upsampling: false` を明示的に設定すると、プロンプトの書き換えを無効にできます。
6. **結果リンク**：画像 URL の有効期限は、対応する `expires_at` の Unix タイムスタンプに従います。期限までに保存してください。
7. **参照 URL にアクセスできない場合**：`temporarily unavailable dependency` というメッセージは、参照画像にアクセスできないことを示す場合があります。URL が公開されており、アクセス制限や期限切れの署名がないことを先に確認してください。