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

# Nano Banana Images API 接続説明

> Nano Banana Image Generation 集成指南 - XHuoAPI

本文は Nano Banana Images API の接続と使用について説明します。このインターフェースは二つの機能をサポートしています：**画像生成（generate）** と **画像編集（edit）**。

## 申請プロセス

使用する前に、XHuoAPI プラットフォームで [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) にアクセスし、Acquire をクリックして開通を申請してください。初回申請では通常、無料の利用枠が利用可能です。開通が完了したら、プラットフォームで API を呼び出すための Bearer Token を取得できます。

## インターフェース概要

* **Base URL**：`https://api.xhuoapi.ai/v1`
* **エンドポイント**：`POST /nano-banana/images`
* **認証方式**：HTTP ヘッダーに `authorization: Bearer {token}` を含める
* **リクエストヘッダー**：
  * `accept: application/json`
  * `content-type: application/json`
* **アクション（action）**：
  * `generate`：テキストプロンプトに基づいて画像を生成
  * `edit`：指定された画像に基づいて編集
* **モデル（model）**（オプション）：
  * `nano-banana`（デフォルト）：Gemini 2.5 Flash Image に基づき、高速で低コスト
  * `nano-banana-2`：Gemini 3.1 Flash Image Preview に基づき、Pro レベルの品質 + Flash スピード
  * `nano-banana-pro`：Gemini 3 Pro Image Preview に基づき、最高品質
* **非同期コールバック**：オプションで、`callback_url` を通じてタスク完了通知と結果を受信

## クイックスタート：画像生成（`action=generate`）

**最小必須パラメータ**：`action`、`prompt`
プロンプトに基づいて直接画像を生成したい場合は、`action` を `generate` に設定し、明確な `prompt` を提供してください。

### リクエスト例（cURL）

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。",
    "count": 1
  }'
```

### リクエスト例（Python）

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": (
        "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。"
        "彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。"
        "シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。"
        "85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。"
        "全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。"
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### 成功返却例

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### フィールド説明

* `success`：今回のリクエストが成功したかどうか。
* `task_id`：タスク ID。
* `trace_id`：トレース ID、問題の調査に役立ちます。
* `data[]`：結果リスト。
  * `prompt`：生成に使用されたプロンプト（エコー）。
  * `image_url`：生成された画像の直接リンク URL。

> 注：`/nano-banana/images` では `action` と `prompt` のみで画像を生成できます。

## 画像編集（`action=edit`）

既存の画像に基づいて編集したい場合は、`action` を `edit` に設定し、`image_urls` で編集対象の画像リンクリスト（1枚または複数枚）を渡し、同時に編集目標を説明する `prompt` を提供してください。

例えば、ここで人物の写真と服の写真を提供し、その人物にその服を着せる場合、画像リンクを同時に渡し、アクションを `edit` に指定します。URL は HTTP URL で、`https` または `http` プロトコルの公開アクセス可能なリンクである必要があります。また、Base64 エンコードされた画像（例：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`）も使用できます。

### リクエスト例（cURL）

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "この男性にこのTシャツを着せてください",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### リクエスト例（Python）

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "この男性にこのTシャツを着せてください",
    "image_urls": [
        "https://cdn.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### 成功返却例

```json theme={null}
{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "この男性にこのTシャツを着せてください",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### フィールド説明

* `image_urls[]`：編集対象の画像 URL リスト（必ず公開アクセス可能である必要があります）。複数枚を渡すことができ、サービスはこれらの素材と `prompt` を組み合わせて編集を完了します。
* その他のフィールドは「画像生成」の返却と同様です。

***

## 非同期コールバック（オプション、推奨）

生成または編集には一定の時間がかかる場合があります。長時間接続がリソースを占有しないように、`callback_url`を使用して**Webhookコールバック**を利用することをお勧めします：

1. リクエストボディに`callback_url`を追加します。例えば、あなたのサーバーのWebhookアドレス（公開アクセス可能で、POST JSONをサポートする必要があります）。
2. APIは**即座に**`task_id`を含むレスポンス（または基本的な結果を含む）を返します。
3. タスクが完了すると、プラットフォームは`POST`方式で完全なJSONを`callback_url`に送信します。`task_id`を使用してリクエストと結果を関連付けることができます。

**コールバックペイロードの例**（フィールド構造は同期成功の返却と一致）：

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "白いシャム猫",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}
```

***

## エラーハンドリング

呼び出しが失敗した場合、標準エラーフォーマットとトレースIDが返されます。一般的なエラーは以下の通りです：

* **400 `token_mismatched`**：リクエストが不正またはパラメータエラー。
* **400 `api_not_implemented`**：インターフェースが未実装（サポートに連絡してください）。
* **401 `invalid_token`**：認証失敗またはトークンが欠如。
* **429 `too_many_requests`**：リクエスト頻度が制限を超過。
* **500 `api_error`**：サーバーエラー。

### エラーレスポンスの例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "内部サーバーエラーです。"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

## パラメータ対照と注意事項

* **必須**：`action`、`prompt`
* **編集専用**：`image_urls`（配列、少なくとも1項目）
* **オプション**：`model`（デフォルトは`nano-banana`、`nano-banana-2`または`nano-banana-pro`も選択可能）、`aspect_ratio`（アスペクト比、例：`1:1`、`16:9`）、`resolution`（解像度、例：`1K`、`2K`、`4K`）、`callback_url`（非同期コールバック用）
* **ヘッダー**：`authorization: Bearer {token}`を必ず提供；`accept`は`application/json`に設定することを推奨
* **画像の可アクセス性**：`image_urls`は公開アクセス可能な直リンク（HTTP/HTTPS）でなければならず、HTTPSの使用を推奨
* **冪等性とトレース**：`task_id`と`trace_id`を保持し、障害調査と結果の関連付けを容易にすること