使用 grsai 平台的 nano-banana 模型生成图片(支持文生图、图生图)
---
name: grsai-nano-banana
description: 使用 grsai 平台的 nano-banana 模型生成图片(支持文生图、图生图)
homepage: https://grsai.ai/
metadata:
{
"openclaw":
{
"emoji": "🎨",
"requires": { "bins": ["uv", "curl"] },
"primaryEnv": "G RSAI_API_KEY",
}
}
---
# 🎨 grsai nano-banana 生图技能
使用 grsai 平台的 nano-banana 系列模型生成高质量图片,支持文生图和图生图。
---
## 📋 使用前准备
### 1. 获取 grsai API Key
1. 访问 https://grsai.ai/zh/dashboard
2. 注册/登录账户
3. 进入 **API Key 管理** 页面
4. 创建新的 API Key
5. **充值** - 确保账户有足够 credits(生图消耗积分)
### 2. 配置 API Key
**方式一:openclaw.json 配置(推荐)**
```json
{
"skills": {
"entries": {
"grsai-nano-banana": {
"apiKey": "sk-your-api-key-here"
}
}
}
}
```
**方式二:环境变量**
```bash
export G RSAI_API_KEY="sk-your-api-key-here"
```
---
## 🚀 使用方法
### 方式一:自然语言对话(推荐)
直接告诉助理你的生图需求,助理会引导你确认方案:
```
用户:帮我生成一张可爱柴犬的头像
助理:好的,使用 nano-banana 生图需要确认以下信息:
【必填】模型、提示词
【选填】尺寸、比例、参考图
...
```
### 方式二:命令行调用
**文生图:**
```bash
uv run ~/.openclaw/workspace/skills/grsai-nano-banana/generate.py \
--prompt "手绘版可爱柴犬头像" \
--model "nano-banana-pro" \
--resolution "1K" \
--aspect-ratio "1:1" \
--api-key "sk-xxx"
```
**图生图:**
```bash
uv run ~/.openclaw/workspace/skills/grsai-nano-banana/generate.py \
--prompt "把这张图变成油画风格" \
--input-image "https://example.com/photo.png" \
--model "nano-banana-pro" \
--api-key "sk-xxx"
```
---
## 📐 参数说明
### 必填参数
| 参数 | 说明 | 示例 |
|------|------|------|
| `--prompt` | 提示词,清晰描述想要的内容 | `"一只可爱的猫咪在草地上"` |
| `--api-key` | grsai API Key | `"sk-xxx"` |
### 选填参数
| 参数 | 默认值 | 选项 | 说明 |
|------|--------|------|------|
| `--model` | `nano-banana-pro` | `nano-banana-pro`<br>`nano-banana-fast`<br>`nano-banana-2`<br>`nano-banana-pro-vip` | 不同模型支持不同分辨率 |
| `--resolution` | `1K` | `1K` / `2K` / `4K` | 分辨率越高,生成时间越长 |
| `--aspect-ratio` | `auto` | `auto` / `1:1` / `16:9` / `9:16`<br>`4:3` / `3:4` / `3:2` / `2:3`<br>`5:4` / `4:5` / `21:9` | 输出图片比例 |
| `--input-image` | - | 图片 URL | 参考图(图生图时使用) |
| `--filename` | 自动生成 | 自定义文件名 | 输出文件名 |
| `--output-dir` | `./generated` | 目录路径 | 输出目录(默认相对于当前目录) |
---
## ⏱️ 生成时间
| 模型 | 1K | 2K | 4K |
|------|-----|-----|-----|
| nano-banana-fast | ~2 分钟 | ~3 分钟 | - |
| nano-banana-pro | ~5-8 分钟 | ~8-12 分钟 | ~15 分钟 |
**注意:**
- 实际时间取决于 grsai 服务器负载
- 高峰时段可能需要更长时间
- 脚本会自动轮询,无需手动等待
---
## 📁 输出文件
**保存路径:** `./generated/`(可自定义)
**命名规则:** `yyyymmdd_模型_描述.png`
**示例:**
- `20260304_pro_手绘版可爱柴犬头像.png`
- `20260304_fast_sunset_beach.png`
**自定义输出目录:**
```bash
uv run generate.py --prompt "xxx" --output-dir "/your/custom/path" --api-key "sk-xxx"
```
---
## ⚠️ 常见问题与踩坑记录
### 1. API 返回 "apikey credits not enough"
**原因:** 账户余额不足
**解决:**
1. 登录 grsai 后台
2. 检查当前 API Key 对应的账户
3. 充值 credits
---
### 2. 生成超时 "gemini timeout... Please try again later"
**原因:** grsai 后端生成时间较长
**解决:**
- 使用异步轮询模式(脚本默认)
- 等待 5 分钟后开始轮询
- 最多轮询 3 次,间隔 1 分钟
- 如仍失败,稍后重试
---
### 3. 内容违规
**原因:** 提示词包含敏感内容
**解决:**
- 调整提示词,避免敏感词汇
- 使用更委婉的描述方式
---
### 4. 模型不支持的分辨率
**原因:** 某些模型有分辨率限制
**限制说明:**
- `nano-banana-pro-vip`:仅支持 1K、2K
- `nano-banana-pro-4k-vip`:仅支持 4K
**解决:** 选择正确的模型或调整分辨率
---
### 5. 接口返回空响应
**原因:** 请求格式不正确
**正确格式:**
```json
{
"model": "nano-banana-pro",
"prompt": "xxx",
"imageSize": "1K",
"aspectRatio": "auto",
"webHook": "-1",
"shutProgress": false
}
```
**注意:** `webHook: "-1"` 是关键,让接口立即返回 task_id
---
### 6. 查询结果时参数错误
**错误:** 使用 `task_id` 参数
**正确:** 使用 `id` 参数
```json
{"id": "1-xxxxx"}
```
---
## 🔧 技术细节
### API 端点
| 接口 | URL | 方法 |
|------|-----|------|
| 提交任务 | `/v1/draw/nano-banana` | POST |
| 查询结果 | `/v1/draw/result` | POST |
### 请求格式
**提交任务:**
```bash
curl -X POST "https://grsai.dakka.com.cn/v1/draw/nano-banana" \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-pro",
"prompt": "手绘版可爱柴犬头像",
"imageSize": "1K",
"aspectRatio": "1:1",
"webHook": "-1",
"shutProgress": false
}'
```
**查询结果:**
```bash
curl -X POST "https://grsai.dakka.com.cn/v1/draw/result" \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{"id": "1-b834c0d4-dda7-4ab2-9ce6-378ea325ab3a"}'
```
### 响应格式
**提交成功:**
```json
{
"code": 0,
"data": {
"id": "1-b834c0d4-dda7-4ab2-9ce6-378ea325ab3a"
},
"msg": "success"
}
```
**查询成功:**
```json
{
"code": 0,
"data": {
"id": "1-xxxxx",
"status": "succeeded",
"progress": 100,
"results": [{
"url": "https://file3.aitohumanize.com/file/xxx.png"
}]
},
"msg": "success"
}
```
---
## 📝 更新日志
- **2026-03-04** - 初始版本
- 支持文生图、图生图
- 异步轮询模式
- 自动保存至 `./generated/` 目录
- 智能文件命名
---
## 🔗 相关链接
- grsai 官网:https://grsai.ai/
- grsai 后台:https://grsai.ai/zh/dashboard
- 文档:https://grsai.ai/zh/dashboard/documents/nano-banana
don't have the plugin yet? install it then click "run inline in claude" again.