# Agent 生图入门教程：小白也能用 Codex、Claude Code 生成图片 不会写代码也能用 Agent 生图。复制一条安装命令，再告诉 Codex、Claude Code 或 Cursor 想画什么，Agent 会配置 Key、生成图片并保存到本地。 这篇教程写给第一次使用 Agent 生图的人。你不需要会写代码，也不用研究模型参数。 完成安装后，只要对 Agent 说一句： ```text 帮我生成一张夏日柠檬汽水广告图，保存到项目里。 ``` Agent 会替你完成选模型、提交任务、等待结果和保存图片。 ## 先看最简单的用法 整个过程只有四步： 1. 复制一条安装命令。 2. 把 Skill 设为 Agent 的全局默认生图工具。 3. 告诉 Agent 想画什么。 4. 第一次使用时，按提示复制一次 API Key。 以后再次生图，通常只需要第 3 步，而且不必每次重复指定 Skill。 ## 开始前需要准备什么 准备下面三样东西： - 一个可以使用的 Agent，例如 Codex、Claude Code 或 Cursor。 - Node.js。运行 `npx --version`，如果能看到版本号，就已经准备好了。 - Python 3。运行 `python3 --version`；Windows 也可以试试 `python --version`。 - 一个 Kaien API 账号。API Key 可以等第一次生图时再创建。 如果 `npx --version` 没有显示版本号，请先从 [Node.js 官网](https://nodejs.org/) 安装 LTS 版本。 如果两个 Python 命令都没有显示 Python 3 版本，请从 [Python 官网](https://www.python.org/downloads/) 安装。Skill 只使用 Python 自带功能，不需要另外安装 Python 库。 ## 第一步：复制安装命令 找到你正在使用的 Agent，只复制对应的那一行。看不懂命令里的参数也没关系。 不知道在哪里运行命令时，可以把整行命令发给有本地操作权限的 Agent，并说“请帮我运行这条安装命令”。如果它不能代你执行，再把命令粘贴到电脑的终端里。 ### 我用 Codex ```bash npx skills add https://kaienapi.com --skill kaien-gpt-image-2 --global --agent codex --yes ``` ### 我用 Claude Code ```bash npx skills add https://kaienapi.com --skill kaien-gpt-image-2 --global --agent claude-code --yes ``` ### 我用 Cursor ```bash npx skills add https://kaienapi.com --skill kaien-gpt-image-2 --global --agent cursor --yes ``` 看到 `kaien-gpt-image-2` 或安装成功提示，就可以继续了。 第一次运行时看到 `npm warn exec`，通常只是 `npx` 正在下载安装工具，不代表安装失败。 如果想确认是否安装成功，可以运行： ```bash npx skills list --global ``` ## 第二步：设为全局默认生图 Skill 安装完成后，把下面整段发给 Agent： ```text 请把下面规则添加到你的全局 AGENTS.md；如果你使用的是其他 Agent， 就写入它等价的全局指令文件： 后续所有图片生成、图片编辑和参考图改图任务，都使用 $kaien-gpt-image-2。 ``` 这一步会让 Agent 以后遇到生图或改图任务时自动使用这个 Skill，不需要每次都写“请使用 `$kaien-gpt-image-2`”。 如果 Agent 没有权限修改全局指令文件，它会告诉你应该把这条规则粘贴到哪里。 ## 第三步：直接告诉 Agent 想画什么 安装后回到 Agent 对话框，复制下面这句话： ```text 请使用 $kaien-gpt-image-2 帮我生成一张图片。 画面是一杯冰镇柠檬汽水，浅蓝色背景，阳光从右边照进来。 保存到项目的 generated 文件夹。 ``` 如果你没有写模型、尺寸或图片格式，Agent 会使用适合新手的默认设置： - 普通模型：`gpt-image-2` - 方形图片：`1024x1024` - PNG 格式 - 保存到当前项目的 `generated/` 文件夹 你只需要关注“想画什么”，其他设置以后再学也不迟。 ## 第四步：第一次使用时设置 API Key 第一次生图时，Agent 可能会告诉你“还缺少 Kaien API Key”。这不是报错，只是还没有绑定你的账号。 按照下面做一次： 1. 打开 [Kaien API Token 页面](https://kaienapi.com/console/token)。 2. 创建一个新的 API Key。 3. 复制 Key。 4. 回到你信任的本地 Agent 对话，把 Key 粘贴给它。 Agent 会保存 Key，然后继续刚才的图片任务。以后通常不需要再粘贴。 Key 默认保存在你的电脑上： ```text ~/.config/kaienapi/api_key ``` 它不会被写进当前项目代码。不要把 Key 发到群聊、公开网页、GitHub Issue 或截图里。更多安全说明见 [API Key 鉴权](/docs/quickstart/authentication)。 如果你不想把 Key 粘贴到 Agent 对话，也可以手动设置环境变量： ```bash ``` Windows PowerShell： ```powershell $env:KAIEN_API_KEY="你的 API Key" ``` ## 怎样算成功了 图片完成后，Agent 会告诉你保存位置，例如： ```text 图片已生成： - 文件：./generated/lemon-soda.png - 规格：gpt-image-2 · 1024x1024 · PNG - 自动重试：0 次 ``` 点击文件路径或在项目文件夹中打开它，就能看到图片。 ## 不会写提示词怎么办 不需要背“提示词公式”。按照这个模板说人话就可以： ```text 帮我生成【什么东西】，用于【什么场景】， 希望是【什么风格或颜色】，保存到【哪个文件夹】。 ``` 例如： ```text 帮我生成一张无线耳机产品海报，用于电商首页。 白色背景，真实摄影风格，画面简洁，保存到项目里。 ``` Agent 会把这句话整理成模型更容易理解的描述，但不会擅自改变你的主体和要求。 ## 可以直接复制的生图示例 | 你想做什么 | 可以这样告诉 Agent | |---|---| | 公众号配图 | `生成一张关于远程办公的扁平插画，横版，保存到 generated 文件夹。` | | 商品海报 | `生成一张银色耳机商品海报，白底，真实摄影风格，中间留出放标题的位置。` | | App 启动页 | `生成一张紫蓝色渐变的科技感 App 启动页背景，竖版，不要文字。` | | 社交媒体图片 | `生成一张夏日旅行主题的方形社交媒体图片，明亮、有活力。` | | 网站 Hero 图 | `生成一张深色 SaaS 网站 Hero 背景，横版，中间留白，不要文字。` | 如果图片中必须出现一句准确文字，请把文字用引号标出来： ```text 海报中必须写“夏日新品”，这五个字不要改。 ``` ## 想用参考图怎么办 你可以把网上能直接打开的图片链接交给 Agent： ```text 请使用 $kaien-gpt-image-2 参考下面两张图片生成白底全身商品图： 图 1：https://example.com/person.jpg 图 2：https://example.com/outfit.jpg 保留图 1 的人物和发型，衣服参考图 2，保存到 generated/look.png。 ``` 注意：链接打开后应该直接显示图片，不能要求登录，也不能很快过期。 如果图片只存在于你的电脑里，直接把本地路径或 Agent 能访问的附件交给它： ```text 请参考 ./references/person.png，把人物改成红色外套，保存到 generated/look.png。 ``` Skill 会先通过 Kaien 的 `/v1/files` 接口上传本地参考图，再把返回的公开图片地址用于图生图。支持 JPG、PNG、GIF 和 WebP，单张默认不超过 10 MB；不需要你先上传到其他图床。 ## 方图、横图和竖图怎么选 如果你不说，Agent 会根据用途自动选择： | 用途 | Agent 通常选择 | |---|---| | 头像、图标、普通配图 | 方图 `1024x1024` | | 网站横幅、文章头图、Hero 图 | 横图 `1536x1024` | | 海报、手机壁纸、全身人物 | 竖图 `1024x1536` | 你也可以直接说“方图”“横图”或“竖图”，不用记像素数字。 ## 什么时候需要 2K 或 4K 普通网页配图、社交图片和初稿，使用默认的 `gpt-image-2` 就够了。 只有下面情况才建议明确要求更高分辨率： - 图片需要放大或裁切。 - 要制作高清商品图。 - 要制作大尺寸海报或最终交付文件。 示例： ```text 使用 gpt-image-2-4K 生成一张竖版电影海报， 雨夜霓虹城市，顶部留出标题区域，保存到 generated/poster.png。 ``` 2K 和 4K 通常需要更多生成时间，也可能消耗更多额度。第一次尝试建议先用普通尺寸确认画面方向。 ## 为什么失败后会出现多个任务 图片生成偶尔会明确返回失败。为了让小白不用反复点“再试一次”，Skill 默认会使用相同要求重新生成，最多重试 5 次。 需要知道三点： - 第一次生成加 5 次重试，最多可能出现 6 条生成记录。 - 每次重新生成都可能消耗账户额度。 - 如果只是等待超时或网络中断，Agent 不会重复创建任务，而是继续查询原任务。 如果只想尝试一次，可以说： ```text 这次只生成一次，失败后不要自动重试。 ``` ## 常见问题 ### Agent 没有开始生图 明确告诉它使用哪个 Skill： ```text 请使用 $kaien-gpt-image-2 帮我生成图片。 ``` 如果仍然没有反应，运行 `npx skills list --global`，确认列表中有 `kaien-gpt-image-2`。 ### 提示找不到 API Key 打开 [Token 页面](https://kaienapi.com/console/token) 创建 Key，然后把它交给可信的本地 Agent 保存。只需要设置一次。 ### 参考图无法读取 把图片链接复制到浏览器地址栏测试。如果不能直接看到图片，模型通常也读不到。换一个无需登录、不会马上过期的图片链接。 ### 图片一直显示处理中 不要重新提交。告诉 Agent： ```text 继续等待刚才的图片任务，完成后保存到项目里。 ``` Agent 会继续查询刚才那条生成记录，不会因为等待超时重复生成。 ### 尺寸不支持 直接改成“方图”“横图”或“竖图”，让 Agent 使用推荐尺寸。小白不需要自己计算宽高限制。 ### 怎么查看用了多少额度 打开控制台用量页面，或阅读 [用量与余额查询](/docs/quickstart/billing-usage)。第一次尝试建议只生成一张普通尺寸图片。 ## 更新或删除 Skill 更新到最新版本： ```bash npx skills update kaien-gpt-image-2 --global --yes ``` 不再使用时删除： ```bash npx skills remove kaien-gpt-image-2 --global --yes ``` ## 给进阶用户 如果你要把图片生成接入网站、App、自动化工作流或批量任务，请阅读 [GPT Image 2 API 文档](/docs/images-video/gpt-image-2)。Agent Skill 更适合个人创作和项目素材；正式产品接入需要自己处理任务记录、轮询和文件存储。 ## 继续阅读 - [GPT Image 2 模型和异步任务](/docs/images-video/gpt-image-2) - [Kaien API Key 鉴权](/docs/quickstart/authentication) - [用量与余额查询](/docs/quickstart/billing-usage) - [普通 skill.md 和可安装 Skill 的区别](/docs/ai/skill) - [`npx skills` 开源项目](https://github.com/vercel-labs/skills)