🎨 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 配置（推荐）

{
  "skills": {
    "entries": {
      "grsai-nano-banana": {
        "apiKey": "sk-your-api-key-here"
      }
    }
  }
}

方式二：环境变量

export G RSAI_API_KEY="sk-your-api-key-here"

---

🚀 使用方法

方式一：自然语言对话（推荐）

直接告诉助理你的生图需求，助理会引导你确认方案：

用户：帮我生成一张可爱柴犬的头像
助理：好的，使用 nano-banana 生图需要确认以下信息：
      【必填】模型、提示词
      【选填】尺寸、比例、参考图
      ...

方式二：命令行调用

文生图：

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"

图生图：

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 nano-banana-fast nano-banana-2 nano-banana-pro-vip	不同模型支持不同分辨率
--resolution	1K	1K / 2K / 4K	分辨率越高，生成时间越长
--aspect-ratio	auto	auto / 1:1 / 16:9 / 9:16 4:3 / 3:4 / 3:2 / 2:3 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

自定义输出目录：

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. 接口返回空响应

原因： 请求格式不正确

正确格式：

{
  "model": "nano-banana-pro",
  "prompt": "xxx",
  "imageSize": "1K",
  "aspectRatio": "auto",
  "webHook": "-1",
  "shutProgress": false
}

注意： webHook: "-1" 是关键，让接口立即返回 task_id

---

6. 查询结果时参数错误

错误： 使用 task_id 参数

正确： 使用 id 参数

{"id": "1-xxxxx"}

---

🔧 技术细节

API 端点

接口	URL	方法
提交任务	/v1/draw/nano-banana	POST
查询结果	/v1/draw/result	POST

请求格式

提交任务：

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
  }'

查询结果：

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"}'

响应格式

提交成功：

{
  "code": 0,
  "data": {
    "id": "1-b834c0d4-dda7-4ab2-9ce6-378ea325ab3a"
  },
  "msg": "success"
}

查询成功：

{
  "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