Skill: runninghcm/image2 (version 1.0.0)

--- 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 扫描友好） - 本技能会访问外部接口：[REDACTED_SECRET]。 - 接口提供方为可想 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-[REDACTED_SECRET]' \ --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-[REDACTED_SECRET]' ``` ## 工作流（必须按顺序执行） ### 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 - 固定路径：[REDACTED_SECRET] - 固定字段：`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-[REDACTED_SECRET]" \ --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-[REDACTED_SECRET]" \ --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-[REDACTED_SECRET]" ``` ## 快速执行脚本 - `./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`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)