> ## 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 Tasks API の接続と使用

> Nano Banana Image Generation 集成指南 - XHuoAPI

Nano Banana Tasks API の主な機能は、Nano Banana Images API によって生成されたタスク ID を入力することで、そのタスクの実行状況を照会することです。

この文書では、Nano Banana Tasks API の接続説明を詳しく紹介し、簡単に統合し、この API の強力な機能を十分に活用できるようにします。Nano Banana Tasks API を使用することで、Nano Banana Images API のタスク実行状況を簡単に照会できます。

## リクエスト例

Nano Banana Tasks API は、Nano Banana Images API の結果を照会するために使用できます。Nano Banana Images API の使用方法については、文書 [Nano Banana Images API](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f) を参照してください。

Nano Banana Images API サービスから返されたタスク ID を例に、どのようにこの API を使用するかを示します。タスク ID が「4d320ead-4af4-4a55-8f3e-f2afebdf4fd0」であると仮定し、次にタスク ID を渡す方法を示します。

### タスク例画像

<p>
  <img src="https://cdn.xhuoapi.ai/nuiuth.png" width="500" className="m-auto" />
</p>

### リクエストヘッダーとリクエストボディの設定

**Request Headers** には以下が含まれます：

* `accept`：JSON形式のレスポンス結果を受け取ることを指定し、ここには `application/json` を記入します。
* `authorization`：API を呼び出すためのキーで、申請後に直接選択できます。

**Request Body** には以下が含まれます：

* `id`：アップロードされたタスク ID。
* `action`：タスクの操作方法。

設定は以下の図のようになります：

<p>
  <img src="https://cdn.xhuoapi.ai/nuiuth.png" width="500" className="m-auto" />
</p>

### コード例

ページの右側には、さまざまな言語のコードが自動生成されていることがわかります。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/r1u4vl.png" width="500" className="m-auto" />
</p>

一部のコード例は以下の通りです：

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
    "action": "retrieve"
}

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

### レスポンス例

リクエストが成功すると、API はこのタスクの詳細情報を返します。例えば：

```json theme={null}
{
  "_id": "68bc7c3c550a4144a53d0e24",
  "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
  "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
  "application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
  "created_at": 1757183036.787,
  "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
  "request": {
    "action": "generate",
    "prompt": "a white siamese cat"
  },
  "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
  "type": "images",
  "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
  "response": {
    "success": true,
    "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
    "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
    "data": [
      {
        "prompt": "a white siamese cat",
        "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
      }
    ]
  }
}
```

返された結果には複数のフィールドがあり、request フィールドはタスクを開始したときの request body であり、response フィールドはタスク完了後に返される response body です。フィールドの説明は以下の通りです。

* `id`：このタスクを生成するための ID で、今回の生成タスクを一意に識別します。
* `request`：タスク内のリクエスト情報を照会します。
* `response`：タスク内の返却情報を照会します。

## バッチ照会操作

これは複数のタスク ID に対してタスクの詳細を照会するもので、上記とは異なり、action を `retrieve_batch` に選択する必要があります。

**Request Body** には以下が含まれます：

* `ids`：アップロードされたタスク ID の配列。
* `action`：タスクの操作方法。

例は以下の通りです：

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"],
  "action": "retrieve_batch"
}'
```

### レスポンス例

リクエストが成功すると、API は今回のすべてのバッチタスクの具体的な詳細情報を返します。例えば：

```json theme={null}
{
  "items": [
    {
      "_id": "68bc7c3c550a4144a53d0e24",
      "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
      "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610",
      "application_id": "8afd681a-2a4e-4265-aecb-43970094c019",
      "created_at": 1757183036.787,
      "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07",
      "request": {
        "action": "generate",
        "prompt": "a white siamese cat"
      },
      "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
      "type": "images",
      "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
      "response": {
        "success": true,
        "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0",
        "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png"
          }
        ]
      }
    }
  ],
  "count": 1
}
```

返された結果には複数のフィールドがあり、items はバッチタスクの具体的な詳細情報を含んでいます。各タスクの具体的な情報は上記のフィールドと同じで、フィールド情報は以下の通りです。

* `items`：バッチタスクのすべての具体的な詳細情報。これは配列であり、各配列の要素は上記の単一タスクの返却結果の形式と同じです。
* `count`：ここでのバッチ照会タスクの個数。

## エラーハンドリング

APIを呼び出す際にエラーが発生した場合、APIは対応するエラーコードとメッセージを返します。例えば：

* `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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、Nano Banana Tasks APIを使用して単一またはバッチタスクのすべての具体的な詳細情報を照会する方法を理解しました。この文書が、APIの接続と使用をより良くする手助けとなることを願っています。ご不明な点がございましたら、いつでも当社の技術サポートチームにお問い合わせください。