Back to Details

canghe-image-gen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Image Generation (AI SDK)

图像生成（AI SDK）

Official API-based image generation. Supports OpenAI, Google, DashScope (阿里通义万象), and Canghe providers.
基于官方API的图像生成工具，支持OpenAI、Google、DashScope（阿里通义万象）以及Canghe等服务商。

Script Directory

脚本目录

Agent Execution:
  1. SKILL_DIR
    = this SKILL.md file's directory
  2. Script path = 
    ${SKILL_DIR}/scripts/main.ts
Agent执行步骤:
  1. SKILL_DIR
    = 当前SKILL.md文件所在目录
  2. 脚本路径 = 
    ${SKILL_DIR}/scripts/main.ts

Preferences (EXTEND.md)

偏好设置（EXTEND.md）

Use Bash to check EXTEND.md existence (priority order):
bash
undefined
使用Bash检查EXTEND.md文件是否存在（优先级顺序）：
bash
undefined

Check project-level first

优先检查项目级目录

test -f .canghe-skills/canghe-image-gen/EXTEND.md && echo "project"
test -f .canghe-skills/canghe-image-gen/EXTEND.md && echo "project"

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)

然后检查用户级目录（跨平台：$HOME适用于macOS/Linux/WSL）

test -f "$HOME/.canghe-skills/canghe-image-gen/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────┬───────────────────┐
│                       Path                       │     Location      │
├──────────────────────────────────────────────────┼───────────────────┤
│ .canghe-skills/canghe-image-gen/EXTEND.md          │ Project directory │
├──────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.canghe-skills/canghe-image-gen/EXTEND.md    │ User home         │
└──────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ Use defaults                                                              │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Default provider | Default quality | Default aspect ratio | Default image size | Default models

Schema: `references/config/preferences-schema.md`
test -f "$HOME/.canghe-skills/canghe-image-gen/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────┬───────────────────┐
│                       路径                       │     位置          │
├──────────────────────────────────────────────────┼───────────────────┤
│ .canghe-skills/canghe-image-gen/EXTEND.md          │ 项目目录          │
├──────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.canghe-skills/canghe-image-gen/EXTEND.md    │ 用户主目录        │
└──────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│   结果     │                                  操作                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│   已找到   │ 读取、解析并应用配置                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│   未找到   │ 使用默认配置                                                              │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md支持配置项**：默认服务商 | 默认画质 | 默认宽高比 | 默认图像尺寸 | 默认模型

配置 schema: `references/config/preferences-schema.md`

Usage

使用方法

bash
undefined
bash
undefined

Basic

基础用法

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只猫" --image cat.png

With aspect ratio

指定宽高比

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一幅风景画" --image out.png --ar 16:9

High quality

高质量生成

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只猫" --image out.png --quality 2k

From prompt files

从文件读取提示词

npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

With reference images (Google multimodal or OpenAI edits)

使用参考图（Google多模态或OpenAI编辑）

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "改成蓝色" --image out.png --ref source.png

With reference images (explicit provider/model)

使用参考图（指定服务商/模型）

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "改成蓝色" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png

Specific provider

指定服务商

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只猫" --image out.png --provider openai

DashScope (阿里通义万象)

DashScope（阿里通义万象）

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope

Canghe third-party gateway

Canghe第三方网关

npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider canghe
undefined
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider canghe
undefined

Options

可选参数

OptionDescription
--prompt <text>
, 
-p
Prompt text
--promptfiles <files...>
Read prompt from files (concatenated)
--image <path>
Output image path (required)
--provider google|openai|dashscope|canghe
Force provider (default: google)
--model <id>
, 
-m
Model ID (
--ref
with OpenAI requires GPT Image model, e.g. 
gpt-image-1.5
)
--ar <ratio>
Aspect ratio (e.g., 
16:9
, 
1:1
, 
4:3
)
--size <WxH>
Size (e.g., 
1024x1024
)
--quality normal|2k
Quality preset (default: 2k)
--imageSize 1K|2K|4K
Image size for Google (default: from quality)
--ref <files...>
Reference images. Supported by Google multimodal, OpenAI edits (GPT Image models), and Canghe (
image_url
). If provider omitted: Google first, then OpenAI, then Canghe
--n <count>
Number of images
--json
JSON output
参数说明
--prompt <text>
, 
-p
提示文本
--promptfiles <files...>
从文件读取提示文本（多文件内容会拼接）
--image <path>
输出图像路径（必填）
--provider google|openai|dashscope|canghe
强制指定服务商（默认：google）
--model <id>
, 
-m
模型ID（使用
--ref
时，OpenAI需要GPT Image模型，例如
gpt-image-1.5
）
--ar <ratio>
宽高比（例如：
16:9
、
1:1
、
4:3
）
--size <WxH>
图像尺寸（例如：
1024x1024
）
--quality normal|2k
画质预设（默认：2k）
--imageSize 1K|2K|4K
Google图像尺寸（默认：由画质预设决定）
--ref <files...>
参考图。支持Google多模态、OpenAI编辑（GPT Image模型）以及Canghe（
image_url
）。若未指定服务商：优先Google，其次OpenAI，最后Canghe
--n <count>
生成图像数量
--json
输出JSON格式结果

Environment Variables

环境变量

VariableDescription
OPENAI_API_KEY
OpenAI API key
GOOGLE_API_KEY
Google API key
DASHSCOPE_API_KEY
DashScope API key (阿里云)
CANGHE_API_KEY
Canghe API key
OPENAI_IMAGE_MODEL
OpenAI model override
GOOGLE_IMAGE_MODEL
Google model override
DASHSCOPE_IMAGE_MODEL
DashScope model override (default: z-image-turbo)
CANGHE_IMAGE_MODEL
Canghe model override (default: gemini-3-pro-image-preview)
OPENAI_BASE_URL
Custom OpenAI endpoint
GOOGLE_BASE_URL
Custom Google endpoint
DASHSCOPE_BASE_URL
Custom DashScope endpoint
CANGHE_BASE_URL
Custom Canghe endpoint (default: 
https://api.canghe.ai/v1
)
Load Priority: CLI args > EXTEND.md > env vars > 
<cwd>/.canghe-skills/.env
> 
~/.canghe-skills/.env
变量说明
OPENAI_API_KEY
OpenAI API密钥
GOOGLE_API_KEY
Google API密钥
DASHSCOPE_API_KEY
DashScope API密钥（阿里云）
CANGHE_API_KEY
Canghe API密钥
OPENAI_IMAGE_MODEL
覆盖默认OpenAI模型
GOOGLE_IMAGE_MODEL
覆盖默认Google模型
DASHSCOPE_IMAGE_MODEL
覆盖默认DashScope模型（默认：z-image-turbo）
CANGHE_IMAGE_MODEL
覆盖默认Canghe模型（默认：gemini-3-pro-image-preview）
OPENAI_BASE_URL
自定义OpenAI端点
GOOGLE_BASE_URL
自定义Google端点
DASHSCOPE_BASE_URL
自定义DashScope端点
CANGHE_BASE_URL
自定义Canghe端点（默认：
https://api.canghe.ai/v1
）
加载优先级：CLI参数 > EXTEND.md > 环境变量 > 
<cwd>/.canghe-skills/.env
> 
~/.canghe-skills/.env

Provider Selection

服务商选择逻辑

  1. --ref
    provided + no 
    --provider
    → auto-select Google first, then OpenAI, then Canghe
  2. --provider
    specified → use it (if 
    --ref
    , must be 
    google
    or 
    openai
    or 
    canghe
    )
  3. Only one API key available → use that provider
  4. Multiple available → default to Google
  1. 提供了
    --ref
    参数但未指定
    --provider
    → 自动优先选择Google，其次是OpenAI，最后是Canghe
  2. 指定了
    --provider
    参数 → 使用该服务商（若使用
    --ref
    ，服务商必须为
    google
    、
    openai
    或
    canghe
    ）
  3. 仅存在一个可用的API密钥 → 使用对应服务商
  4. 存在多个可用API密钥 → 默认使用Google

Quality Presets

画质预设

PresetGoogle imageSizeOpenAI SizeUse Case
normal
1K1024pxQuick previews
2k
(default)		2K2048pxCovers, illustrations, infographics
Google imageSize: Can be overridden with 
--imageSize 1K|2K|4K
预设Google图像尺寸OpenAI尺寸适用场景
normal
1K1024px快速预览
2k
（默认）		2K2048px封面、插画、信息图
Google图像尺寸：可通过
--imageSize 1K|2K|4K
参数覆盖默认值

Aspect Ratios

支持的宽高比

Supported: 
1:1
, 
16:9
, 
9:16
, 
4:3
, 
3:4
, 
2.35:1
  • Google multimodal: uses 
    imageConfig.aspectRatio
  • Google Imagen: uses 
    aspectRatio
    parameter
  • OpenAI: maps to closest supported size
支持的宽高比：
1:1
、
16:9
、
9:16
、
4:3
、
3:4
、
2.35:1
  • Google多模态：使用
    imageConfig.aspectRatio
    参数
  • Google Imagen：使用
    aspectRatio
    参数
  • OpenAI：自动映射到最接近的支持尺寸

Generation Mode

生成模式

Default: Sequential generation (one image at a time). This ensures stable output and easier debugging.
Parallel Generation: Only use when user explicitly requests parallel/concurrent generation.
ModeWhen to Use
Sequential (default)Normal usage, single images, small batches
ParallelUser explicitly requests, large batches (10+)
Parallel Settings (when requested):
SettingValue
Recommended concurrency4 subagents
Max concurrency8 subagents
Use caseLarge batch generation when user requests parallel
Agent Implementation (parallel mode only):
undefined
默认模式：串行生成（一次生成一张图像）。该模式可确保输出稳定，便于调试。
并行生成：仅在用户明确要求并行/并发生成时使用。
模式适用场景
串行（默认）常规使用、单张图像、小批量生成
并行用户明确要求、大批量生成（10张以上）
并行配置（仅在请求时启用）：
配置项取值
推荐并发数4个子Agent
最大并发数8个子Agent
适用场景用户要求并行时的大批量生成
Agent实现方式（仅并行模式）：
undefined

Launch multiple generations in parallel using Task tool

使用Task工具并行启动多个生成任务

Each Task runs as background subagent with run_in_background=true

每个Task以后台子Agent运行，run_in_background=true

Collect results via TaskOutput when all complete

所有任务完成后通过TaskOutput收集结果

undefined
undefined

Error Handling

错误处理

  • Missing API key → error with setup instructions
  • Generation failure → auto-retry once
  • Invalid aspect ratio → warning, proceed with default
  • Reference images with unsupported provider/model → error with fix hint (switch to Google multimodal or OpenAI GPT Image edits)
  • 缺少API密钥 → 报错并提供设置指引
  • 生成失败 → 自动重试一次
  • 无效宽高比 → 发出警告，使用默认值继续执行
  • 不支持参考图的服务商/模型 → 报错并提供修复提示（切换至Google多模态或OpenAI GPT Image编辑）

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.
可通过EXTEND.md进行自定义配置。路径及支持的配置项请查看偏好设置章节。