picflex-openclaw（picflex OpenClaw 开发）

PicFlex OpenClaw Skill

本 Skill 通过 PicFlex Open API 调用图像生成能力，不是 MCP 服务。所有结果都必须来自真实 HTTP 接口返回。

强制规则

1. 必须先检查 PICFLEX_API_KEY 是否已配置，未配置时停止并提示去 OpenClaw Skills 配置中填写。
2. 文生图直接调用 POST /api/open/text2image/tasks，图生图直接调用 POST /api/open/image2image/tasks，不得混用。
3. 不需要在创建任务前调用 GET /api/open/credits/balance；是否可创建任务，以任务创建接口的真实返回为准。
4. 图生图遇到本地图片或对话附件时，必须先调用 POST /api/open/uploads/image 上传图片，从响应中取 downloadUrl，再把这个 URL 作为 referenceUrl 去调用 POST /api/open/image2image/tasks；如果用户已经提供公网图片 URL，可以直接作为 referenceUrl。
5. 任务创建成功后，必须每 5 秒轮询一次任务接口，直到状态变成 completed 或 failed。
6. 禁止编造 taskId、状态、积分余额、失败原因或结果图片 URL。
7. 成功时必须使用固定返回模板：先输出模型、状态、消耗积分、任务 ID，再输出 图片 URL:，下一行放真实图片 URL，再空一行后输出 ![result](真实URL)；图片 URL 和 Markdown 图片必须各自单独成行，不能放进列表项或代码块。

配置

• 申请 API Key：登录 PicFlex，在 Profile 页的 API Keys 区域创建。
• 环境变量：PICFLEX_API_KEY
• OpenClaw Skills 配置方式： 变量名固定是 PICFLEX_API_KEY 变量值只填写 PicFlex 后台生成的明文 key，例如 pflex_xxxxxxxxx
• 不要填写成 PICFLEX_API_KEY=pflex_xxxxxxxxx
• 不要填写成 Bearer pflex_xxxxxxxxx
• 不要带引号、前后空格或换行
• 该值在 OpenClaw Skills 配置中保存一次后会持续生效，后续使用这个 Skill 不需要每次重复输入，除非你手动修改、删除或撤销该 key
• 认证方式：Authorization: Bearer ${PICFLEX_API_KEY}
• 站点主页：https://www.picflex.app

工作流选择

• 用户只有文字描述，没有提供图片或改图意图：走文生图
• 用户提供了图片、图片链接，或明确说“改图 / 编辑这张图 / 参考这张图”：走图生图

标准调用顺序

文生图

1. POST /api/open/text2image/tasks
2. GET /api/open/text2image/tasks/{taskId}，每 5 秒轮询一次
3. 状态 completed 时展示 resultUrls

图生图

1. 如果用户给的是本地图片或附件：POST /api/open/uploads/image
2. 从上传响应中读取 downloadUrl
3. POST /api/open/image2image/tasks
4. 请求体中使用 referenceUrl = downloadUrl
5. GET /api/open/image2image/tasks/{taskId}，每 5 秒轮询一次
6. 状态 completed 时展示 resultUrls

API 参考

Base URL: https://www.picflex.app

1. 上传图片

POST /api/open/uploads/image

• Content-Type: multipart/form-data
• 字段：file

返回字段：

• fileUrl
• downloadUrl

图生图使用规则：

• 如果来源是本地图片或对话附件，后续创建图生图任务时应优先使用上传接口返回的 downloadUrl
• 不要把本地文件路径直接传给 referenceUrl
• 如果上传接口同时返回 fileUrl 和 downloadUrl，优先使用 downloadUrl

2. 创建文生图任务

POST /api/open/text2image/tasks

常用字段：

• prompt
• model
• aspectRatio
• resolution
• outputFormat
• negativePrompt

返回字段：

• taskId
• status
• requiredCredits
• availableCredits
• reservedCredits
• spendableCredits

3. 查询文生图任务

GET /api/open/text2image/tasks/{taskId}

4. 创建图生图任务

POST /api/open/image2image/tasks

常用字段：

• referenceUrl 或 referenceUrls
• prompt
• model
• ratio
• resolution
• outputFormat

返回字段：

• taskId
• status
• requiredCredits
• availableCredits
• reservedCredits
• spendableCredits

图生图入参规则：

• 本地图片或附件：先上传，再把上传响应里的 downloadUrl 传入 referenceUrl
• 公网图片 URL：可直接传入 referenceUrl
• 多张本地图片：逐张上传，拿到多个 downloadUrl 后传入 referenceUrls

5. 查询图生图任务

GET /api/open/image2image/tasks/{taskId}

任务状态说明

• queued: 已提交，等待执行
• processing: 执行中
• completed: 已完成，可读取 resultUrls
• failed: 失败，查看 failCode 和 failMessage

结果展示要求

• 成功时严格使用下面的固定格式，不要改成项目符号列表：

生成好了。
模型：`{model}`
状态：`{status}`
消耗积分：`{consumedCredits}`
任务 ID：`{taskId}`
图片 URL：
{resultUrl}

![result]({resultUrl})

• 如果有多张图，保留前 4 行摘要不变，然后按下面格式逐张输出：

图片 1 URL：
{resultUrl1}

![result-1]({resultUrl1})

图片 2 URL：
{resultUrl2}

![result-2]({resultUrl2})

• 图片 URL： 后面的真实 URL 必须单独成行，方便 OpenClaw 聊天框识别和预览。
• Markdown 图片也必须单独成行，不要放进项目符号、引用块、代码块或括号说明里。
• 如果结果还未完成，只汇报当前真实状态，不要假装已经生成结束。

错误处理

• 401 invalid_api_key：提示用户去 OpenClaw Skills 配置中设置正确的 PICFLEX_API_KEY
• 如果用户确认已经配置但仍然报 401 invalid_api_key，优先检查：

1. Skills 配置框里填的是不是裸 key 值，而不是 PICFLEX_API_KEY=... 2. 有没有误加 Bearer 3. key 是否以 pflex_ 开头 4. key 是否来自 PicFlex Profile 页的 API Keys，而不是别的令牌 5. key 是否已经被 revoke

• 402 insufficient_credits：提示接口返回的 requiredCredits 以及当前可用信息，停止调用
• 404 task_not_found：提示任务不存在或不属于当前 key 对应账户
• 其他错误：直接转述接口返回的 error、errorType、failMessage

调用示例

文生图

curl 'http://localhost:3000/api/open/text2image/tasks' \
  -H 'Authorization: Bearer YOUR_PICFLEX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Create a cinematic product poster with soft golden light",
    "model": "nano-banana-2",
    "resolution": "1k",
    "ratio": "auto",
    "outputFormat": "jpg"
  }'

图生图

curl 'http://localhost:3000/api/open/image2image/tasks' \
  -H 'Authorization: Bearer YOUR_PICFLEX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "referenceUrl": "https://your-uploaded-image.example.com/reference.webp",
    "prompt": "Turn this photo into a cinematic product poster with soft light",
    "model": "nano-banana-2",
    "resolution": "1k",
    "ratio": "auto",
    "outputFormat": "jpg"
  }'

示例请求意图

• “给我生成一张极简风咖啡海报” -> 文生图
• “把这张产品图改成高级广告片质感” -> 图生图
• “参考这张图片，生成一版 16:9 的横版封面” -> 图生图