词元之河 tokenriver 图片生成与编辑

功能

通过词元之河（tokenriver）的统一图片接口完成两类任务，支持 tokenriver 平台提供的所有图片模型：

• 文生图：POST https://api.tokenriver.cn/v1/images/generations，由文本提示词生成全新图片。
• 图片编辑：POST https://api.tokenriver.cn/v1/images/edits，基于一张或多张输入图片进行修改、局部重绘、换背景、风格调整或合成。

tokenriver 是 OpenAI 兼容协议的企业级大模型网关，可用图片模型通过模型列表接口动态获取：

• 模型列表：GET https://api.tokenriver.cn/v1/models，由 scripts/list_models.py 调用并过滤图片模型。
• 首次使用时必须先选定模型：运行 list_models.py 查看可用图片模型，询问用户选择哪个，再用 save_model.py 持久化到用户主目录的配置文件 ~/.tokenriver-image/config.json。之后 generate_image.py / edit_image.py 会自动读取该模型。
• 用户要更换模型时，重新展示可用模型并让用户选择，再次 save_model.py 覆盖；新选择立即生效，无需重启会话。
• 本 skill 不设默认模型（无任何硬编码默认值），模型完全由用户在首次使用时选定。

核心判断：

• 用户只提供文字并要求“生成、画、做、设计一张新图片”时，走文生图流程，运行 scripts/generate_image.py。
• 用户提供或引用已有图片，并要求“修改、参考、合成、换背景、局部重绘、把这张图改成……”时，走图片编辑流程，运行 scripts/edit_image.py。
• 用户需求是视频、本地离线修图、截图、压缩、裁剪或其他供应商时，不使用本技能，除非用户明确要求切换到 tokenriver。

能力边界

支持：

• 中文/英文提示词文生图。
• 海报、头像、封面、插画、产品图、电商图、宣传图、概念图、角色设定图、场景图等新图片生成。
• 基于一张或多张 png / jpg / jpeg / webp 图片进行编辑。
• 换背景、保留主体、改变风格、多图合成、局部补全或重绘。
• 可选使用 mask 遮罩图进行局部编辑；完全透明区域表示需要编辑的位置。
• 通过 --model 指定 tokenriver 平台支持的任意图片模型；不指定时读取配置文件或 TOKENRIVER_IMAGE_MODEL，都没有时报错提示先选模型。
• 指定数量、尺寸、质量、输出格式、背景透明度、审核级别等参数。
• 保存 URL 图片、base64 图片或原始 JSON 响应。

不支持：

• 视频生成、图生视频、视频续写。
• 本地离线图片处理、截图、压缩、裁剪、无 API 的离线修图。
• 非 tokenriver 的图片供应商，除非用户明确要求改用 tokenriver。

执行流程

1. 判断任务类型：
   - 无输入图片且目标是创建新图：选择文生图。
   - 有输入图片、参考图、遮罩或“修改这张图”的目标：选择图片编辑。
2. 校验 API Key：读取顺序为环境变量 TOKENRIVER_API_KEY → skill 配置文件 ~/.tokenriver-image/config.json → Windows 注册表旧值。
   - 用户直接提供 API Key 时，运行 scripts/save_api_key.py --api-key-stdin 保存到配置文件；通过 stdin 传入，不写入文档、日志或 memory。
   - 环境变量 TOKENRIVER_API_KEY 优先于配置文件；若环境中已有旧 Key，提示用户更新或清除环境变量。
3. 校验已选模型：读取顺序为 --model 参数 → 配置文件 ~/.tokenriver-image/config.json → 环境变量 TOKENRIVER_IMAGE_MODEL。
   - 首次使用（未设置模型）：运行 scripts/list_models.py（或 --keyword image）展示当前可用图片模型，询问用户要用哪一个；用户确认后运行 python scripts/save_model.py --model <model_id> 持久化。
   - 用户明确要求更换模型：重新运行 list_models.py 展示可用模型，让用户选择，再用 save_model.py 覆盖。
   - 已有选定模型且用户未要求更换：直接使用，无需再问。
4. 提取提示词；缺失时先询问用户想生成什么或如何修改图片。
5. 编辑场景提取待编辑图片路径；缺失时先询问用户提供图片文件。
6. 需要确认接口限制时读取 references/api_docs.md；需要模型清单时读取 references/models.md 或运行 list_models.py；需要示例时读取 references/examples.md；遇到失败时读取 references/troubles.md。
7. 根据任务类型运行对应脚本。
8. 检查输出：有图片则交付图片；只有 JSON 则说明响应结构和下一步。

参数

通用参数

• prompt：必填，图片生成或编辑提示词。
• model：可选。读取顺序：--model 参数 → 配置文件 ~/.tokenriver-image/config.json → 环境变量 TOKENRIVER_IMAGE_MODEL。三者都没有时脚本会报错并提示先选模型。首次使用必须先用 list_models.py + save_model.py 选定并保存模型；本 skill 不设默认模型。
• n：可选，默认 1（始终发送），范围 1 到 10。
• size：可选。不传时请求不带 size 字段，由模型默认尺寸决定；常用 1024x1024、1536x1024、1024x1536、auto。不同模型支持的尺寸可能不同，以 references/models.md 或接口返回为准。
• quality：可选。不传时请求不带 quality 字段；常用 high、medium、low、auto（部分模型为 standard / hd）。
• format：可选。指定时作为请求体字段发送，并作为 base64 图片的保存扩展名；不传时不发送该字段，图片按 png 保存。可为 png / jpeg / webp。
• output_dir：可选，默认应使用当前工作区下的任务专属目录。

文生图专用说明

• 只有用户显式指定的 size / quality / format 才会进入 JSON 请求体，未指定的字段不发送，由模型取默认值。
• 请求使用标准 OpenAI 兼容字段 model。

图片编辑专用参数

• image / images：必填，待编辑图片路径，可传一张或多张。
• mask：可选，遮罩 PNG；透明区域表示要编辑的位置；应小于 4MB 且尺寸与第一张图片一致。
• background：可选，支持 transparent、opaque、auto；不传时不发送该字段。
• moderation：可选，支持 low、auto；不传时不发送该字段。
• response_format：可选，仅部分模型使用；多数图片模型默认按 base64/URL 响应解析，不要主动传该参数。

调用脚本

> 下文命令中的 scripts/xxx.py 均相对本 skill 根目录（SKILL.md 所在目录）。实际执行时请拼上 skill 的安装路径，或先切换到该目录；工作目录不同时直接照抄会找不到脚本。

首次使用：选定模型（必须先做一次）

# 1. 查看当前可用图片模型
python "scripts/list_models.py"
python "scripts/list_models.py" --keyword image

# 2. 用户确认后保存选定的模型（之后 generate/edit 会自动复用）
python "scripts/save_model.py" --model <model_id>

> 本 skill 不设默认模型。未保存模型时，generate_image.py / edit_image.py 会报错并提示先选模型。

更换模型

# 重新查看可用模型，确认后覆盖
python "scripts/list_models.py" --keyword image
python "scripts/save_model.py" --model <new_model_id>

保存用户提供的 API Key

python "scripts/save_api_key.py" --api-key-stdin

通过 stdin 传入 Key，避免出现在命令参数与进程列表中；若用 echo / printf 管道传入，Key 仍会留在命令文本里，属已知限制。Key 保存到 ~/.tokenriver-image/config.json（POSIX 下权限为 600）。

文生图

python "scripts/generate_image.py" \
  --prompt "一只穿宇航服的小龙虾，赛博朋克海报风格" \
  --n 1 \
  --size 1024x1024 \
  --quality auto \
  --format png \
  --output-dir "C:/path/to/output"

> --model 省略时自动读取已保存的模型选择（配置文件 ~/.tokenriver-image/config.json 优先于 TOKENRIVER_IMAGE_MODEL）；也可显式传 --model <model_id> 临时覆盖（不改已保存的默认模型）。

编辑单张图片

python "scripts/edit_image.py" \
  --image "C:/path/to/input.png" \
  --prompt "保留主体，把背景改成雪山日出，真实摄影风格" \
  --n 1 \
  --size 1024x1024 \
  --quality auto \
  --output-dir "C:/path/to/output"

编辑多张参考图并合成

python "scripts/edit_image.py" \
  --image "C:/path/to/person.png" \
  --image "C:/path/to/product.png" \
  --prompt "将人物和产品自然合成到同一张电商海报中，保留人物面部特征" \
  --output-dir "C:/path/to/output"

局部编辑

python "scripts/edit_image.py" \
  --image "C:/path/to/input.png" \
  --mask "C:/path/to/mask.png" \
  --prompt "只修改透明遮罩区域，将天空改成晚霞" \
  --output-dir "C:/path/to/output"

脚本行为

scripts/generate_image.py：

• 发送 POST https://api.tokenriver.cn/v1/images/generations。
• 添加 Content-Type: application/json、Accept: application/json、Authorization: Bearer <key>。
• 校验 prompt、n、quality、format、size。
• 使用标准请求字段 model 传模型名；模型读取顺序为 --model → 配置文件 ~/.tokenriver-image/config.json → TOKENRIVER_IMAGE_MODEL，都没有时报错并提示先选模型。
• 未显式指定的 size / quality / format 不会进入请求体，由模型取默认值。

scripts/edit_image.py：

• 发送 POST https://api.tokenriver.cn/v1/images/edits。
• 添加 Accept: application/json、Authorization: Bearer <key>，请求体使用 multipart/form-data。
• 校验 image、mask、prompt、n、size、quality、background、moderation。
• 将每个 --image 作为 image 字段重复上传，兼容多图数组语义。
• 未显式指定的 size / quality / background / moderation 不会进入请求体，由模型取默认值。
• 模型读取顺序同 generate：--model → 配置文件 → TOKENRIVER_IMAGE_MODEL，都没有时报错。

scripts/list_models.py：

• 发送 GET https://api.tokenriver.cn/v1/models。
• 解析返回的模型列表，对疑似图片模型（id 或描述含 image/imagen/flux/seedream/dall-e/gpt-image 等）做高亮标记。
• 支持 --keyword 在全部模型中按子串过滤（疑似图片模型带 [IMAGE] 标记）、--all 显示全部模型、--json 输出原始响应。
• 首次使用或更换模型时用来向用户展示可选清单。

scripts/save_model.py：

• 把用户选定的模型 id 持久化到配置文件 ~/.tokenriver-image/config.json（不写环境变量或 shell rc 文件）。
• 模型名非敏感，用 --model <id> 直接传入即可。
• 再次运行可覆盖（用于换模型）；配置文件优先于环境变量，更换后立即生效。

两个图片脚本都会：

• 遇到 url 字段时下载图片。
• 遇到 b64_json、base64、image_base64 字段时保存图片。
• 单张图片下载或解码失败时输出 WARNING 并继续保存其余图片；全部失败才以错误退出。
• 遇到未知结构时保存 response.json。
• 输出 metadata.json 记录接口、状态、原始响应路径、保存文件路径和保存错误。

输出

成功时（stdout，一行一个文件路径）：

Saved image files:
C:/path/to/output/image_1.png

同时写入 metadata.json，记录接口、状态、模型、原始响应路径和保存文件路径。

接口返回 2xx 但未识别出图片字段时（stdout，退出码 0）：

No direct image URL/base64 fields detected. Raw response saved to: C:/path/to/output/response.json
Metadata saved to: C:/path/to/output/metadata.json

此时应读取 response.json 判断响应结构并继续处理。

失败时：stderr 输出 ERROR: ...（含接口错误摘要与处理建议），退出码非 0；原始响应仍保存在 response.json。

异常处理

• 未检测到 API Key：提示进入 https://tokenriver.cn/dashboard 创建 Key，并设置 TOKENRIVER_API_KEY。
• 未选定模型（首次使用）：脚本报错提示先运行 list_models.py 选模型；助手应展示可用图片模型，询问用户选择，确认后用 save_model.py 保存。
• 用户要更换模型：重新运行 list_models.py 展示可用模型，让用户选择，再用 save_model.py 覆盖。
• 401 / 403：提示检查 API Key 和 Bearer 授权格式。
• 余额/额度不足：提示进入 https://tokenriver.cn/dashboard 充值后重试。
• 400 / 422：
• 文生图优先检查 prompt、model、n、size、quality、format。
• 图片编辑优先检查图片格式/大小、prompt、model、n、size、quality、mask。
• 若疑似模型名不支持，运行 scripts/list_models.py 确认可用模型清单。
• 413：提示图片文件过大；编辑场景单图应小于 25MB，遮罩应小于 4MB。
• 非 2xx：提取 error、message、msg、code、detail 后说明失败原因。
• 多次出现错误，但无法确定原因提示进入 https://tokenriver.cn/dashboard 联系客服寻求帮助。
• 未知响应：保存原始响应并总结 HTTP 状态，不暴露密钥。
• 图片保存失败（URL 下载失败或 base64 损坏）：脚本告警并继续保存其余图片；全部失败时以错误退出，response.json 保留原始数据。

模型支持说明

• tokenriver 是企业级大模型网关，图片模型随平台更新而变化。
• 本 skill 不在脚本中硬编码模型白名单，--model 传什么发什么，由 tokenriver 接口校验。
• 想确认当前可用图片模型，运行 scripts/list_models.py，或参考 references/models.md 中的常见型号（可能滞后）。
• 不同模型的参数支持范围（尺寸、质量、是否支持编辑、response_format 等）由模型决定；遇到参数校验失败时以接口返回的错误提示为准。

安全规则

• 不把 API Key 写入 SKILL.md、reference、memory 或项目文件。
• 优先使用 TOKENRIVER_API_KEY，避免用命令行 --api-key。
• 用户提供 Key 时，用 save_api_key.py --api-key-stdin 保存到 ~/.tokenriver-image/config.json；该方式只避免 Key 出现在命令参数与进程列表中，用管道传入时 Key 仍会出现在命令文本里，不要在总结或日志中复述。
• 对日志、报错、总结中的 Authorization 和 Key 做脱敏。
• 未经用户明确要求，不把用户图片、生成结果或提示词上传到其他服务。