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

# Google Nano Banana

> 基于 Gemini 2.5 Flash Image 的图像生成模型 API 接口

<Info>
  `google/nano-banana` 底层调用的是 Google 的 `gemini-2.5-flash-image` 模型。
</Info>

## 查询任务状态

提交任务后，可通过统一的查询端点查看任务进度并获取生成结果：

<Card title="获取任务详情" icon="magnifying-glass" href="/api-reference/common/get-task-detail">
  了解如何查询任务状态并获取生成结果
</Card>

<Tip>
  生产环境中，建议使用 `callback_url`
  参数接收生成完成的自动通知，而非轮询状态端点。
</Tip>

## 授权

<ParamField header="Authorization" type="string" required>
  Bearer Token 认证。格式：`Bearer sk-xxxxxx`

  <Expandable defaultOpen title="详细说明">
    * 获取 API Key：访问 [API Key 管理页面](https://ruxa.ai/dashboard/api-keys) 获取您的 API Key

    * 使用方法：在请求头中添加 `Authorization: Bearer YOUR_API_KEY`

    * 注意事项：请妥善保管您的 API Key，切勿泄露给他人

    * 若怀疑 API Key 泄露，请立即在管理页面重置
  </Expandable>
</ParamField>

## 请求体

请求体格式为 `application/json`。

<ParamField body="model" type="string" required default="google/nano-banana">
  模型名称，固定为 `google/nano-banana`
</ParamField>

<ParamField body="callback_url" type="string">
  任务完成后的回调地址。系统会向该 URL POST 任务状态与结果。

  示例：`https://your-domain.com/api/callback`
</ParamField>

<ParamField body="input" type="object" required>
  生成任务的输入参数

  <Expandable defaultOpen title="子属性">
    <ParamField body="input.prompt" type="string" required>
      用于图像生成的文本提示词

      <Expandable defaultOpen title="示例">
        ```
        "爱因斯坦刚刚完成相对论后发布的一条超写实风格的推文。"
        ```
      </Expandable>
    </ParamField>

    <ParamField body="input.output_format" type="enum<string>" default="png">
      生成图像的输出格式

      可用选项：`png`, `jpeg`
    </ParamField>

    <ParamField body="input.size" type="enum<string>" default="1:1">
      生成图像的尺寸比例

      可用选项：`1:1`, `9:16`, `16:9`, `3:4`, `4:3`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`, `auto`
    </ParamField>

    <ParamField body="input.image" type="string">
      参考图片的 URL 地址（用于图生图场景）

      <Expandable defaultOpen title="示例">
        ```
        "https://example.com/your-image.png"
        ```
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## 响应

<ResponseField name="code" type="integer" required>
  响应状态码

  <Expandable defaultOpen title="状态码说明">
    * `200`: 成功 - 请求已处理完成

    * `401`: 未授权 - 身份验证凭据缺失或无效

    * `402`: 积分不足 - 账户积分不足以执行该操作

    * `404`: 未找到 - 请求的资源或端点不存在

    * `422`: 验证错误 - 请求参数未通过校验

    * `429`: 速率限制 - 已超出该资源的请求频次限制

    * `500`: 服务器错误 - 处理请求时发生意外故障
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string" required>
  响应消息，请求失败时为错误描述
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable defaultOpen title="子属性">
    <ResponseField name="data.taskId" type="string" required>
      任务 ID，用于查询任务状态
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.ruxa.ai/api/v1/tasks/create \
    --header 'Authorization: Bearer sk-xxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "callback_url": "https://your-domain.com/api/callback",
      "input": {
        "prompt": "把背景变成像素风",
        "output_format": "png",
        "aspect_ratio": "16:9",
        "image_input": ["https://file.aiquickdraw.com/custom-page/akr/section-images/1756223420389w8xa2jfe.png"]
      },
      "model": "google/nano-banana"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "taskId": "task_gemini-2.5-flash-image_1766304530229_cf4dafd2"
    }
  }
  ```
</ResponseExample>