Nano Banana 文字轉圖片

01

概覽

使用文字轉圖像端點搭配支援的模型。使用回傳的 Task ID 擷取其狀態，或提供 callback_url 以接收下方說明的回呼通知。

快速入門

建立 API 金鑰並將其設定為 RUNAPI_API_KEY。
選擇支援的模型，並傳送本文符合該模型結構描述的 POST 請求。
儲存返回的任務 ID，然後輪詢直到終止狀態，或處理下方說明的回呼。

POST /api/v1/nano_banana/text_to_image

基礎 URL: https://runapi.ai
API 版本: v1
身分驗證: Authorization: Bearer YOUR_API_TOKEN

02

支援的模型

開啟模型頁面以查看目前的定價、速率限制及商業用途詳情。

03

請求綱要

JSON 請求內文

欄位及允許值取決於所選模型。若提供 callback_url，其將接收下方記錄的 Task 交付內容。

nano-banana7 個欄位

aspect_ratiostring

選填 允許的值: 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto

callback_urlstring

選填

modelstring

選填

output_formatstring

選填 允許的值: png, jpeg, jpg

output_resolutionstring

選填

promptstring

選填

reference_image_urlsarray

選填

nano-banana-27 個欄位

aspect_ratiostring

選填 允許的值: 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9, auto

callback_urlstring

選填

modelstring

選填

output_formatstring

選填 允許的值: png, jpeg, jpg

output_resolutionstring

選填 允許的值: 1k, 2k, 4k

promptstring

選填

reference_image_urlsarray

選填

nano-banana-2-lite5 個欄位

aspect_ratiostring

必填 允許的值: 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9, auto 預設值: auto

callback_urlstring

選填

modelstring

選填

promptstring

必填 範圍: 1 - 20000

reference_image_urlsarray

選填 項目數上限: 10

nano-banana-pro7 個欄位

aspect_ratiostring

選填 允許的值: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto

callback_urlstring

選填

modelstring

選填

output_formatstring

選填 允許的值: png, jpeg, jpg

output_resolutionstring

選填 允許的值: 1k, 2k, 4k

promptstring

選填

reference_image_urlsarray

選填 項目數上限: 8

條件規則

當所有列出的條件均符合時，這些需求即適用。

當 model = nano-banana-2-lite

必填

不接受

output_resolution, output_format

04

建立接受記錄

HTTP 202

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}

05

輪詢處理中

HTTP 200

GET /api/v1/nano_banana/text_to_image/:id

回應綱要

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}

06

輪詢已完成

HTTP 200

GET /api/v1/nano_banana/text_to_image/:id

回應綱要

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "images": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "images",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "images": [
    {
      "url": "https://cdn.runapi.ai/public/samples/image.jpg"
    }
  ],
  "status": "completed"
}

07

輪詢失敗

HTTP 200

GET /api/v1/nano_banana/text_to_image/:id

回應綱要

JSON

{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}

08

客戶回呼：已完成

HTTP 200

POST callback_url

回應綱要

JSON

{
  "properties": {
    "id": {
      "type": "string"
    },
    "images": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "images"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "id": "tsk_reference_demo",
  "images": [
    {
      "url": "https://cdn.runapi.ai/public/samples/image.jpg"
    }
  ],
  "status": "completed"
}

09

客戶回呼：失敗

HTTP 200

POST callback_url

回應綱要

JSON

{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}

10

錯誤

HTTP 401

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Authentication required"
}

11

錯誤

HTTP 401

GET /api/v1/nano_banana/text_to_image/:id

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Authentication required"
}

12

錯誤

HTTP 400

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "人類可讀的錯誤訊息。",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "人類可讀的驗證摘要。",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "以公開請求欄位為索引鍵的驗證訊息，每個欄位包含一組人類可讀的字串陣列。",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

回應範例

JSON

{
  "error": "model must be one of: nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro"
}

13

錯誤

HTTP 402

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Insufficient balance"
}

14

錯誤

HTTP 429

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "API key credit limit exceeded"
}

15

錯誤

HTTP 409

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "The request uses features that are not supported for the selected model"
}

16

錯誤

HTTP 429

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Rate limit reached. Please retry later."
}

17

錯誤

HTTP 503

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Service under maintenance, please try again later"
}

18

錯誤

HTTP 504

POST /api/v1/nano_banana/text_to_image

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "The request timed out"
}

19

錯誤

HTTP 404

GET /api/v1/nano_banana/text_to_image/:id

回應綱要

JSON

{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

JSON

{
  "error": "Task with id 'tsk_reference_demo' not found"
}

20

產生的程式碼範例

直接使用 cURL，或為您的程式語言安裝 SDK。每個範例均會提交本參考中所示的已驗證請求。

安裝

Shell

pip install runapi-nano-banana

PYTHON

import os
from runapi.nano_banana import NanoBananaClient

client = NanoBananaClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_image.create(
  model="nano-banana-pro",
  prompt="A cobalt vase on white marble.",
  aspect_ratio="1:1"
)

安裝

Shell

npm install @runapi.ai/nano-banana

JAVASCRIPT

import { NanoBananaClient } from "@runapi.ai/nano-banana";

const client = new NanoBananaClient({ apiKey: process.env.RUNAPI_API_KEY });
const task = await client.textToImage.create({
  "model": "nano-banana-pro",
  "prompt": "A cobalt vase on white marble.",
  "aspect_ratio": "1:1"
});

CURL

curl -X POST https://runapi.ai/api/v1/nano_banana/text_to_image \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"model":"nano-banana-pro","prompt":"A cobalt vase on white marble.","aspect_ratio":"1:1"}'

安裝

Shell

go get github.com/runapi-ai/nano-banana-sdk/go@latest

GO

package main

import (
  "context"
  "log"
  "os"

  "github.com/runapi-ai/core-sdk/go/option"
  nanobanana "github.com/runapi-ai/nano-banana-sdk/go/nanobanana"
)

func main() {
  client, err := nanobanana.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
  if err != nil {
    log.Fatal(err)
  }

  task, err := client.TextToImage.Create(context.Background(), nanobanana.TextToImageParams{
    Model: nanobanana.TextToImageModel("nano-banana-pro"),
    Prompt: "A cobalt vase on white marble.",
    AspectRatio: nanobanana.AspectRatio("1:1"),
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = task
}

21

Nano Banana 文字轉圖片

概覽

快速入門

端點

支援的模型

請求綱要

條件規則

建立接受記錄

回應範例

輪詢處理中

回應範例

輪詢已完成

回應範例

輪詢失敗

回應範例

客戶回呼：已完成

回應範例

客戶回呼：失敗

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

錯誤

回應範例

產生的程式碼範例

安裝

相關指南