image2

SKILL.md

---
name: image2
version: 1.0.0
description: 使用 image2 接口创建图片生成任务（文生图/参考生图）。当用户提到"生成图片""图生图""海报图""封面图"，或明确要求比例（如 16:9、9:16）时应使用本 skill。调用接口 /api/v1/user_task/asyncCreateWithCost，核心参数含 user_input.modelType（text2img/img2img）、prompt、size、urls（img2img 必填，最多 8 张）。需 x-api-key（kexiangai.com）。Do NOT use for video generation, OCR, or non-generative image editing.
metadata:
  requires:
    bins: ["curl", "python3"]
    env: ["X_API_KEY"]
  network:
    endpoints: ["https://kexiangai.com/api/v1/user_task/asyncCreateWithCost", "https://kexiangai.com/api/v1/user_task/get/passAuth/{id}"]
  secrets:
    primary: "X_API_KEY"
  storage:
    optional: ["~/.config/image2/.env (only when user explicitly enables --use-local-key)"]
---

## 安全声明（ClawHub 扫描友好）

- 本技能会访问外部接口：`/api/v1/user_task/asyncCreateWithCost`。
- 接口提供方为可想 AI（`kexiangai.com` 生态），调用前应由用户自行确认可信性与合规性。
- 默认不从本地配置文件读取密钥；仅当用户明确使用 `--use-local-key` 时才读取 `~/.config/image2/.env`。
- 推荐优先使用会话级环境变量 `X_API_KEY`，避免不必要的本地持久化。

## 运行依赖与环境变量

- 必需二进制：`curl`、`python3`
- 本地密钥读取相关：`grep`、`cut`、`tr`、`tail`（仅 `--use-local-key` 模式）
- 必需环境变量：`X_API_KEY`（推荐）
- 可选环境变量：`IMAGE2_BASE_URL`（默认 `https://kexiangai.com`）

你是 "image2 任务创建与查询" 技能。你的职责是稳定、可重复地创建 image2 图片任务，并在创建成功后主动查询直到返回最终结果。

## CRITICAL

- 调用接口前必须完成参数校验，不能跳过。
- 不得泄露完整 `x-api-key`，日志与回显仅允许掩码展示。
- 用户未提供必填信息时，先补齐再调用 API。
- `img2img` 模式下 `urls` 为必填，且最多 8 张。
- **单轮对话只允许创建一次任务，绝不重复提交同参数任务。**
- **禁止自动循环重试；任何重试都必须先说明可能继续消耗积分并获得用户明确同意。**
- API 创建的是异步任务：本技能必须在创建成功后继续调用查询接口，直到任务结束（成功或失败）。

## 何时使用

- 用户想创建 image2 文生图任务（`text2img`）
- 用户想基于参考图创建任务（`img2img`）
- 用户需要指定比例（如 `1:1`、`3:4`、`16:9`）

触发短语示例：

- "帮我用 image2 生成一张海报"
- "按这几张图做 img2img"
- "给我创建一个 16:9 的封面图任务"
- "生成一张 3:4 的产品图"

## 何时不要使用

- 用户要做视频生成、视频处理或音频处理
- 用户要做 OCR、文档解析、表格识别
- 用户只需要非生成式编辑（裁剪、压缩、加边框等）

## 输入参数

- `x-api-key`：必填，请求头字段，获取地址 `kexiangai.com`
- `cost_type`：固定 `1`
- `business_url`：固定 `gpt-image2/img`
- `user_input.modelName`：默认 `GPT-Image-2`
- `user_input.modelType`：必填，`text2img` 或 `img2img`
- `user_input.prompt`：必填，字符串
- `user_input.size`：必填，比例字符串
- `user_input.urls`：`img2img` 必填，URL 字符串数组，最多 8 项

支持的 `size`：

- `auto`
- `1:1`
- `3:2`
- `2:3`
- `16:9`
- `9:16`
- `4:3`
- `3:4`
- `21:9`
- `9:21`
- `1:3`
- `3:1`
- `2:1`
- `1:2`

## 认证与 Key 复用

支持用户首次配置后长期复用，无需每次重复输入。

### Key 读取优先级（从高到低）

1. 本次对话显式输入的 `x-api-key`
2. 环境变量 `X_API_KEY`
3. 本地持久化文件 `~/.config/image2/.env`（仅在显式允许时读取）

### 首次配置（只需一次）

```bash
mkdir -p ~/.config/image2
cat > ~/.config/image2/.env << 'EOF'
X_API_KEY=你的x-api-key
EOF
chmod 600 ~/.config/image2/.env
```

## 核心接口

详细字段说明见 `references/api-guide.md`。

```bash
curl --location 'https://kexiangai.com/api/v1/user_task/asyncCreateWithCost' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_X_API_KEY>' \
--data '{
  "cost_type": 1,
  "business_url": "gpt-image2/img",
  "user_input": {
    "modelName": "GPT-Image-2",
    "modelType": "text2img",
    "prompt": "为护肤产品生成一张极简海报",
    "size": "3:4"
  }
}'
```

```bash
curl --location 'https://kexiangai.com/api/v1/user_task/get/passAuth/<TASK_ID>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_X_API_KEY>'
```

## 工作流（必须按顺序执行）

### Step 1: 收集与补齐输入

- 必填：`prompt`、`modelType`、`size`
- 条件必填：`urls`（当 `modelType=img2img`）
- 必填认证：`x-api-key`（可从优先级策略自动读取）

### Step 2: 参数校验与归一化

- `modelType` 仅允许 `text2img` 或 `img2img`
- `size` 必须在支持列表内
- `prompt` 必须非空
- `img2img` 时：`urls` 必须为 URL 字符串数组，长度 1-8
- `text2img` 时：`urls` 默认为空数组（可省略）

### Step 3: 组装请求并调用 API

- 固定路径：`/api/v1/user_task/asyncCreateWithCost`
- 固定字段：`cost_type=1`、`business_url=gpt-image2/img`
- 请求头：`Content-Type: application/json` + `x-api-key`
- 调用前先输出"请求摘要 + 预计积分消耗提醒"，并等待用户确认（如"确认创建"）
- 创建成功后，记录任务 `id` 与参数摘要，避免同轮重复提交

### Step 4: 创建成功后立即提示并进入查询

- 先明确输出：任务已创建成功 + 任务 ID
- 紧接着调用查询接口：`/api/v1/user_task/get/passAuth/{id}`
- 对 `task_status` 为 `pending`/`running` 持续轮询
- 轮询间隔建议 5-10 秒，避免过于频繁请求

### Step 5: 直到返回最终结果再结束

- 当 `task_status=success`：返回最终结果（优先 `service_output.imgUrls`、其次 `service_output.imgUrl`）
- 当 `task_status=failed`/`error`/`canceled`：返回失败状态与 `service_output.failReason`
- 达到最大查询次数仍未结束：明确告知超时，并给出继续查询建议

## 标准错误处理

- 缺少 `x-api-key`：提示去 `kexiangai.com` 获取，并说明可用 `scripts/set_key.sh` 持久化
- 缺少 `prompt`：提示补充提示词后再创建
- `modelType` 非法：提示仅支持 `text2img`/`img2img`
- `size` 非法：返回支持列表并要求重选
- `img2img` 缺少 `urls`：提示至少提供 1 张参考图 URL
- `urls` 超过 8 张：提示精简到 8 张以内
- 401/403：提示 key 无效、过期或权限不足
- 429：提示限流，不自动重试
- 5xx：提示服务异常，建议用户确认后重试一次
- 查询阶段超时：提示任务可能仍在执行中，可继续按任务 ID 查询

## 防重复提交策略

- 默认策略：每个用户请求最多 1 次创建调用。
- 允许第 2 次调用的条件：用户明确要求"重试"或"修改参数后重建"。
- 已成功返回任务 ID 后，本轮对话禁止再次提交相同参数。

## 输出质量检查清单

在最终响应前逐项检查：

- 是否已完成必填参数校验
- 是否正确处理了 `img2img` 的 `urls` 约束
- 是否对 key 做了掩码处理
- 是否在创建成功后输出了任务 ID
- 是否已进入查询并持续到最终状态

## 可复用命令模板

```bash
# 1) 首次配置 key（只需一次）
mkdir -p ~/.config/image2
./scripts/set_key.sh

# 2) 会话变量方式（推荐）
export X_API_KEY='你的x-api-key'

# 3) text2img 任务创建
curl --location 'https://kexiangai.com/api/v1/user_task/asyncCreateWithCost' \
--header 'Content-Type: application/json' \
--header "x-api-key: $X_API_KEY" \
--data '{
  "cost_type": 1,
  "business_url": "gpt-image2/img",
  "user_input": {
    "modelName": "GPT-Image-2",
    "modelType": "text2img",
    "prompt": "生成科技风产品海报",
    "size": "16:9"
  }
}'

# 4) img2img 任务创建
curl --location 'https://kexiangai.com/api/v1/user_task/asyncCreateWithCost' \
--header 'Content-Type: application/json' \
--header "x-api-key: $X_API_KEY" \
--data '{
  "cost_type": 1,
  "business_url": "gpt-image2/img",
  "user_input": {
    "modelName": "GPT-Image-2",
    "modelType": "img2img",
    "prompt": "基于参考图生成新品海报",
    "size": "3:4",
    "urls": ["https://example.com/reference.png"]
  }
}'

# 5) 按任务 ID 查询
curl --location "https://kexiangai.com/api/v1/user_task/get/passAuth/${TASK_ID}" \
--header 'Content-Type: application/json' \
--header "x-api-key: $X_API_KEY"
```

## 快速执行脚本

- `./scripts/set_key.sh`：交互输入并保存 key 到 `~/.config/image2/.env`
- `echo '你的x-api-key' | ./scripts/set_key.sh --stdin`：从标准输入保存 key
- `X_API_KEY='你的x-api-key' ./scripts/create_task.sh --mode text2img --prompt "提示词" --size "3:4"`
- `X_API_KEY='你的x-api-key' ./scripts/create_task.sh --mode img2img --prompt "提示词" --size "3:4" --url "https://example.com/1.png"`
- 创建后脚本会自动查询直到任务结束，并输出最终结果

## 目录结构（标准）

- `SKILL.md`
- `scripts/set_key.sh`
- `scripts/create_task.sh`
- `references/api-guide.md`
- `assets/`

## 交互模板（对话时）

1. 尝试自动读取 key（`X_API_KEY`，必要时再走本地 `.env`）
2. 若缺 key，提示用户提供 `x-api-key`（`kexiangai.com`）
3. 收集 `modelType`（`text2img`/`img2img`）
4. 收集 `prompt` 与 `size`
5. 若 `img2img`，收集 `urls`（1-8 张）
6. 明确本次只创建一次任务
7. 调用创建接口，先提示任务 ID，再自动轮询查询接口直到返回最终结果

## 常见调试问题

### Skill 不触发

- 检查 `description` 是否覆盖真实表达（如"生成图片""图生图""16:9 封面图"）
- 可用调试问句：`When would you use the image2 skill?`

### 返回 pending 但用户以为失败

- 强调 `pending` 是正常中间状态
- 创建成功后必须继续查询，直到 `success` 或失败态

### 参数被拒绝

- 优先检查 `modelType`、`size`、`urls` 数量与格式
- 确认 `business_url` 固定为 `gpt-image2/img`