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

# DualSeason Duomi Nano Banana

> 在 dualseason.com 使用 Duomi Nano Banana 进行异步文生图和图生图。

Duomi Nano Banana 仅在 `https://dualseason.com` 提供。生成任务采用异步模式：提交后保存 `task_id`，再通过 `GET /v1/tasks/{task_id}` 查询结果。

## 支持的模型

| 模型                               | 说明                         | 价格       |
| -------------------------------- | -------------------------- | -------- |
| `gemini-2.5-flash-image`         | Nano Banana，适合快速生成         | \$0.02/张 |
| `gemini-3-pro-image-preview`     | Nano Banana Pro，适合高质量生成和编辑 | \$0.02/张 |
| `gemini-3.1-flash-image-preview` | Nano Banana 2，支持最高 4K 输出   | \$0.02/张 |

## 文生图

使用 `POST /v1/images/generations` 提交文生图任务。

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl --request POST \
    --url https://dualseason.com/v1/images/generations \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gemini-2.5-flash-image",
      "prompt": "A clean minimal icon of a blue lighthouse on a white background",
      "size": "1024x1024"
    }'
  ```

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

  response = requests.post(
      "https://dualseason.com/v1/images/generations",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "gemini-2.5-flash-image",
          "prompt": "A clean minimal icon of a blue lighthouse on a white background",
          "size": "1024x1024",
      },
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```
</RequestExample>

## 图生图

使用 `POST /v1/images/edits` 提交图生图任务。请求体必须是 JSON，参考图通过 `image_urls` 传入。

<Warning>
  `image_urls` 只接受公网 HTTP(S) 图片 URL，不支持 Base64 或本地文件。最多可传 10 张参考图。
</Warning>

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl --request POST \
    --url https://dualseason.com/v1/images/edits \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "Place the logo on a clean white presentation card",
      "image_urls": [
        "https://example.com/reference.png"
      ],
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }'
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch('https://dualseason.com/v1/images/edits', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gemini-3-pro-image-preview',
      prompt: 'Place the logo on a clean white presentation card',
      image_urls: ['https://example.com/reference.png'],
      aspect_ratio: '1:1',
      image_size: '1K',
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

## 请求参数

<ParamField header="Authorization" type="string" required>
  Bearer API Key，例如 `Bearer sk-xxxxxxxx`。
</ParamField>

<ParamField body="model" type="string" required>
  使用上方列出的三个模型之一。
</ParamField>

<ParamField body="prompt" type="string" required>
  描述需要生成或编辑的图像。
</ParamField>

<ParamField body="image_urls" type="string[]">
  图生图必填。传入 1 至 10 个公网 HTTP(S) 图片 URL。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  输出宽高比。支持 `auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9` 和 `21:9`。
</ParamField>

<ParamField body="image_size" type="string">
  输出分辨率。可传 `1K`、`2K` 或 `4K`。`K` 必须大写。模型是否支持对应分辨率取决于 Duomi 上游能力。
</ParamField>

<ParamField body="size" type="string">
  OpenAI 兼容尺寸。常用值包括 `1024x1024`、`1536x1024`、`1024x1536`、`1280x720` 和 `720x1280`。服务会转换为对应宽高比。
</ParamField>

## 提交响应

提交成功后，Duomi 返回任务 ID：

<ResponseExample>
  ```json 200 theme={null} theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "task_id": "f34952eb-ddcf-366d-bd96-a2fd7dbb1483"
    }
  }
  ```
</ResponseExample>

## 查询结果

使用提交响应中的 `task_id` 查询任务。建议每 5 至 10 秒查询一次。

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl --request GET \
    --url https://dualseason.com/v1/tasks/YOUR_TASK_ID \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

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

  task_id = "YOUR_TASK_ID"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  while True:
      response = requests.get(
          f"https://dualseason.com/v1/tasks/{task_id}",
          headers=headers,
          timeout=30,
      )
      response.raise_for_status()
      task = response.json()
      if task["status"] in {"completed", "failed"}:
          print(task)
          break
      time.sleep(10)
  ```
</RequestExample>

任务状态包括：

* `queued`：任务正在排队。
* `in_progress`：任务正在生成。
* `completed`：生成成功，从 `result_url` 或 `result.images[0].url` 获取图片。
* `failed`：生成失败，查看响应中的错误信息。

<ResponseExample>
  ```json 200 theme={null} theme={null}
  {
    "status": "completed",
    "result": {
      "images": [
        {
          "file_name": "output.png",
          "url": "https://cdn.example.com/output.png"
        }
      ]
    },
    "task_id": "f34952eb-ddcf-366d-bd96-a2fd7dbb1483",
    "progress": "100%",
    "result_url": "https://cdn.example.com/output.png"
  }
  ```
</ResponseExample>

<Info>
  真实测试中文生图约 40 秒完成，图生图约 130 秒完成。实际耗时受提示词、参考图和上游队列影响。结果 URL 可能带有效期，请及时下载保存。
</Info>