图像生成与 image-gen Skill

这一页只讲 Pragma 的图像生成能力：网页画图、本地 image-gen skill、API Key 配置和常见失败处理。

先用网页画图

如果你只是想快速生成图片，优先使用网页入口，不需要配置本机环境。

方式	地址	适合谁
站内画图	`https://pragma.academic-ruc.cc/apps/images`	已登录 Pragma 的普通用户
独立 image 工作台	`https://image.academic-ruc.cc/`	需要独立图像工作台的用户
本地 image-gen skill	`~/.pragma/skills/image-gen/`	需要让 Codex / Claude Code 等 agent 自动生成图片的用户

本地 image-gen skill 是什么

image-gen skill 是一个本机 agent 工具包。配置完成后，你可以让 Codex / Claude Code 这类 agent 调用 Pragma 的图片模型完成文生图任务。

它适合这些场景：

给论文、汇报、课程项目生成配图草案。
给网页、文档、社区帖子生成封面或示意图。
让 agent 在任务流程里自动生成图片，而不是你手动打开网页。

安装前准备

你需要准备：

一个可用的 Pragma API Key。
Windows PowerShell、Windows WSL 或 macOS 终端。
Python 3.9 或更高版本。

Windows 用户优先检查：

powershell

py -3 --version

如果提示找不到 py，改试：

powershell

python --version

WSL / macOS 用户检查：

bash

python3 --version

安装 image-gen skill

Windows PowerShell

复制下面整段运行：

powershell

$skill = "$HOME\.pragma\skills\image-gen"
New-Item -ItemType Directory -Force "$skill\scripts" | Out-Null
iwr https://docs.academic-ruc.cc/skill/image-gen/SKILL.md -OutFile "$skill\SKILL.md"
iwr https://docs.academic-ruc.cc/skill/image-gen/INSTALL.md -OutFile "$skill\INSTALL.md"
iwr https://docs.academic-ruc.cc/skill/image-gen/scripts/image_gen.py -OutFile "$skill\scripts\image_gen.py"
py -3 "$skill\scripts\image_gen.py" --help

如果 py 不可用，把最后一行改为：

powershell

python "$skill\scripts\image_gen.py" --help

Windows WSL

在 WSL 终端中运行：

bash

mkdir -p ~/.pragma/skills/image-gen/scripts
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/SKILL.md -o ~/.pragma/skills/image-gen/SKILL.md
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/INSTALL.md -o ~/.pragma/skills/image-gen/INSTALL.md
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/scripts/image_gen.py -o ~/.pragma/skills/image-gen/scripts/image_gen.py
python3 ~/.pragma/skills/image-gen/scripts/image_gen.py --help

macOS

在终端中运行：

bash

mkdir -p ~/.pragma/skills/image-gen/scripts
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/SKILL.md -o ~/.pragma/skills/image-gen/SKILL.md
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/INSTALL.md -o ~/.pragma/skills/image-gen/INSTALL.md
curl -fsSL https://docs.academic-ruc.cc/skill/image-gen/scripts/image_gen.py -o ~/.pragma/skills/image-gen/scripts/image_gen.py
python3 ~/.pragma/skills/image-gen/scripts/image_gen.py --help

安装成功会看到什么

成功时会看到 image_gen.py 的参数说明，里面会出现 --prompt、--model、--size 等参数。

Windows 上文件通常位于：

text

C:\Users\你的用户名\.pragma\skills\image-gen\

WSL / macOS 上文件通常位于：

text

~/.pragma/skills/image-gen/

关键文件：

文件	用途
`SKILL.md`	给 agent 读取的 skill 说明
`scripts/image_gen.py`	实际调用图像生成接口的脚本
`INSTALL.md`	本机安装说明

配置 API Key

最简单的方式是只在当前终端临时设置 API Key。

Windows PowerShell：

powershell

$env:PRAGMA_API_KEY = "sk-your-key"

WSL / macOS：

bash

export PRAGMA_API_KEY="sk-your-key"

这种方式关闭终端后会失效，但更安全。

如果你希望长期保存，可以自己创建本机配置文件：

Windows PowerShell：

powershell

New-Item -ItemType Directory -Force "$HOME\.pragma" | Out-Null
'{"api_key":"sk-your-key"}' | Set-Content -Encoding UTF8 "$HOME\.pragma\config"

WSL / macOS：

bash

mkdir -p ~/.pragma
printf '{"api_key":"sk-your-key"}\n' > ~/.pragma/config
chmod 600 ~/.pragma/config

不要把这个文件提交到 Git，也不要发给别人。

测试 API Key

Windows PowerShell：

powershell

$headers = @{ Authorization = "Bearer $env:PRAGMA_API_KEY" }
Invoke-RestMethod "https://pragma.academic-ruc.cc/v1/models" -Headers $headers

WSL / macOS：

bash

curl -fsSL https://pragma.academic-ruc.cc/v1/models \
  -H "Authorization: Bearer $PRAGMA_API_KEY"

成功时会返回模型列表。失败时常见状态：

表现	常见原因
`401`	API Key 错误、失效或多复制了空格
`403`	当前 Key 无权访问目标模型
连接超时	本机网络或 DNS 问题

真实生成一张图片

Windows PowerShell：

powershell

py -3 "$HOME\.pragma\skills\image-gen\scripts\image_gen.py" `
  --prompt "simple academic poster background, clean layout" `
  --model gpt-image-2 `
  --size 1024x1024

WSL / macOS：

bash

python3 ~/.pragma/skills/image-gen/scripts/image_gen.py \
  --prompt "simple academic poster background, clean layout" \
  --model gpt-image-2 \
  --size 1024x1024

生成结果会保存到本机输出目录。具体路径以终端输出为准。

可以直接丢给 agent 的 prompt

如果你想让 Codex / Claude Code 帮你配置，可以把下面这段直接发给 agent：

text

请帮我配置 Pragma image-gen skill。我的系统是 Windows PowerShell。
要求：
1. 在 ~/.pragma/skills/image-gen/ 下创建 skill 目录；
2. 从 docs.academic-ruc.cc 下载 SKILL.md、INSTALL.md 和 scripts/image_gen.py；
3. 不保存 API Key，除非我单独确认；
4. 安装后运行 image_gen.py --help 验证；
5. 把安装路径和验证结果告诉我。

WSL 用户把第一行改成：

text

我的系统是 Windows WSL，请在 WSL 里配置。

macOS 用户把第一行改成：

text

我的系统是 macOS，请在终端里配置。

常见问题

PowerShell 找不到 `py`

改用：

powershell

python "$HOME\.pragma\skills\image-gen\scripts\image_gen.py" --help

如果 python 也找不到，需要先安装 Python。

`image_gen.py --help` 失败

先确认文件存在：

powershell

Test-Path "$HOME\.pragma\skills\image-gen\scripts\image_gen.py"

如果返回 False，重新运行安装命令。

API Key 验证失败

重新复制 API Key，并确认没有多余空格：

powershell

$env:PRAGMA_API_KEY = "sk-your-key"

然后重新测试模型列表。

生图很慢

图像生成不是流式接口。几十秒到数分钟都可能正常。不要只按等待时间判断失败，要看终端最后的错误信息。

生成失败但模型列表正常

可能原因：

当前模型暂时不可用。
prompt 触发了上游限制。
图片尺寸或参数不被模型支持。
网络连接中断。

建议先用更短 prompt 和默认尺寸重试。

图像生成与 image-gen Skill ​

先用网页画图 ​

本地 image-gen skill 是什么 ​

安装前准备 ​

安装 image-gen skill ​

Windows PowerShell ​

Windows WSL ​

macOS ​

安装成功会看到什么 ​

配置 API Key ​

测试 API Key ​

真实生成一张图片 ​

可以直接丢给 agent 的 prompt ​

常见问题 ​

PowerShell 找不到 py ​

image_gen.py --help 失败 ​

API Key 验证失败 ​

生图很慢 ​

生成失败但模型列表正常 ​

图像生成与 image-gen Skill

先用网页画图

本地 image-gen skill 是什么

安装前准备

安装 image-gen skill

Windows PowerShell

Windows WSL

macOS

安装成功会看到什么

配置 API Key

测试 API Key

真实生成一张图片

可以直接丢给 agent 的 prompt

常见问题

PowerShell 找不到 `py`

`image_gen.py --help` 失败

API Key 验证失败

生图很慢

生成失败但模型列表正常