2026-05-14 18:10:57 +08:00

6.6 KiB

Raw Blame History

oneimage - AI 图片生成器

Claude Code Skill — 通过 oneinai API 调用 Gemini 图像模型，支持文生图与图生图

📋 简介

oneimage 是一款 Claude Code Skill 插件，通过 oneinai API 调用 NanoBananaPro（Gemini 3 Pro Image Preview） 模型，在 Claude Code 对话中直接生成高质量图片。支持文生图、图生图编辑、批量并发等多种模式。

🔗 相关链接

资源	地址
GitHub 仓库	deijing/oneimage
oneinai API	https://api.oneinai.com
oneinai 控制台	https://api.oneinai.com/console/token

✨ 功能特点

✅ 文生图：用自然语言描述场景，AI 生成对应图片
✅ 图生图：上传本地图片 + 编辑描述，AI 修改生成新图片
✅ 10 种宽高比：1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9 / 5:4 / 4:5
✅ 3 档分辨率：1K（快速预览）/ 2K（推荐）/ 4K（超高清）
✅ 文字渲染：支持在图片中渲染中文文字（招牌、海报、标语等）
✅ 并发批量：多张图片并发生成，大幅缩短总耗时
✅ 配置文件管理：API Key 存储在本地配置文件，安全便捷

📋 前置要求

Claude Code CLI 已安装
Python 3.10+
oneinai API Key（在 oneinai 控制台创建）

🛠️ 安装

第一步：下载 Skill

# 如果目录不存在，先创建
mkdir -p ~/.claude/skills

# 克隆 oneimage 到 skills 目录
cd ~/.claude/skills
git clone https://github.com/deijing/oneimage.git

安装完成后目录结构如下：

~/.claude/skills/oneimage/
├── SKILL.md                          # Skill 定义文件
├── scripts/
│   ├── generate_oneinai.py           # 文生图脚本
│   └── generate_oneinai_edit.py      # 图生图脚本
└── references/
    └── api-reference.md              # API 参考文档

第二步：安装依赖

pip install httpx

第三步：配置 API Key

三种方式任选其一。

方式 A：交互式配置（推荐）

python ~/.claude/skills/oneimage/scripts/generate_oneinai.py --setup

按提示输入你的 API Key 即可，配置会保存到 ~/.oneimage/config.json。

方式 B：手动创建配置文件

mkdir -p ~/.oneimage
echo '{"api_key": "sk-你的key"}' > ~/.oneimage/config.json

方式 C：环境变量

export ONEINAI_API_KEY="sk-你的key"

💡 API Key 加载优先级 --api-key 命令行参数 > ONEINAI_API_KEY 环境变量 > ~/.oneimage/config.json 配置文件

📖 使用方法

在 Claude Code 中使用

安装配置完成后，在 Claude Code 对话中输入：

/oneimage

然后描述你想要的图片即可。例如：

"画一张江南水乡的风景"
"生成一张 4K 超宽屏的故宫雪景"
"批量生成 5 张不同风格的古风人像"

图生图编辑：

"编辑 /path/to/photo.jpg，把背景改成竹林"

独立脚本使用

也可以脱离 Claude Code，直接在命令行中调用。

文生图：

python ~/.claude/skills/oneimage/scripts/generate_oneinai.py \
  -p "一位中国女性，身穿汉服，站在竹林中，晨雾缭绕" \
  -ar 3:4 \
  -s 2K \
  -o ./output.png

图生图：

python ~/.claude/skills/oneimage/scripts/generate_oneinai_edit.py \
  -i ./photo.jpg \
  -p "将背景改为雪景，保持人物不变" \
  -ar 3:4 \
  -o ./edited.png

批量生成：

# 准备任务文件 tasks.json
cat > tasks.json << 'EOF'
[
  {"prompt": "描述1", "aspect_ratio": "3:4", "size": "2K", "output": "./out1.png"},
  {"prompt": "描述2", "aspect_ratio": "16:9", "size": "1K", "output": "./out2.png"}
]
EOF

# 执行批量生成
python ~/.claude/skills/oneimage/scripts/generate_oneinai.py \
  --batch tasks.json \
  --workers 2

📐 参数速查

文生图（`generate_oneinai.py`）

参数	简写	说明	默认值
`--setup`		交互式配置 API Key
`--api-key`		指定 API Key	从配置加载
`--prompt`	`-p`	图片描述（必填）
`--aspect-ratio`	`-ar`	宽高比	`1:1`
`--size`	`-s`	分辨率（1K/2K/4K）	`2K`
`--output`	`-o`	输出路径	`output.png`
`--batch`	`-b`	批量任务 JSON 文件
`--workers`	`-w`	并发数	自动（默认 2）
`--retry`	`-r`	重试次数（0-10）	`3`

图生图（`generate_oneinai_edit.py`）

参数	简写	说明	默认值
`--setup`		交互式配置 API Key
`--api-key`		指定 API Key	从配置加载
`--input`	`-i`	输入图片路径（必填）
`--prompt`	`-p`	编辑描述（必填）
`--aspect-ratio`	`-ar`	输出宽高比	`1:1`
`--output`	`-o`	输出路径	`output.png`
`--batch`	`-b`	批量任务 JSON 文件
`--workers`	`-w`	并发数	自动（默认 2）
`--retry`	`-r`	重试次数（0-10）	`3`

⚠️ 互斥参数 --prompt 和 --batch 互斥，单图模式和批量模式必须二选一。

📊 分辨率参考

1K（快速预览）

宽高比	分辨率
1:1	1024×1024
16:9	1376×768
9:16	768×1376
4:3	1200×896
3:4	896×1200

2K（推荐）

宽高比	分辨率
1:1	2048×2048
16:9	2752×1536
9:16	1536×2752
4:3	2400×1792
3:4	1792×2400

4K（超高清）

宽高比	分辨率
1:1	4096×4096
16:9	5504×3072
9:16	3072×5504
4:3	4800×3584
3:4	3584×4800

🖼️ 图生图支持格式

格式	支持	备注
JPG / JPEG	✅	推荐
PNG	✅	推荐
WebP	✅
GIF	✅	仅使用第一帧

💡 建议图片大小推荐小于 4MB，过大可能导致上传变慢或超时。

❓ 常见问题

提示「未找到 API Key」？

运行交互式配置命令：

python ~/.claude/skills/oneimage/scripts/generate_oneinai.py --setup

请求超时？

4K 图片生成较慢，脚本已设置充足的超时时间。如果仍然超时，可降低分辨率到 2K 或 1K。

收到 429 错误？

触发了 API 频率限制。脚本会自动指数退避重试（默认 3 次）。可加 --retry 5 增加重试次数。

6.6 KiB Raw Blame History Unescape Escape