PicFlex OpenClaw Skill
本 Skill 通过 PicFlex Open API 调用图像生成能力，不是 MCP 服务。所有结果都必须来自真实 HTTP 接口返回。
强制规则
- 必须先检查
PICFLEX_API_KEY是否已配置，未配置时停止并提示去 OpenClaw Skills 配置中填写。 - 文生图直接调用
POST /api/open/text2image/tasks，图生图直接调用POST /api/open/image2image/tasks，不得混用。 - 不需要在创建任务前调用
GET /api/open/credits/balance；是否可创建任务，以任务创建接口的真实返回为准。 - 图生图遇到本地图片或对话附件时，必须先调用
POST /api/open/uploads/image上传图片，从响应中取downloadUrl，再把这个 URL 作为referenceUrl去调用POST /api/open/image2image/tasks；如果用户已经提供公网图片 URL，可以直接作为referenceUrl。 - 任务创建成功后，必须每 5 秒轮询一次任务接口，直到状态变成
completed或failed。 - 禁止编造
taskId、状态、积分余额、失败原因或结果图片 URL。 - 成功时必须使用固定返回模板：先输出模型、状态、消耗积分、任务 ID，再输出
图片 URL:，下一行放真实图片 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
工作流选择
- 用户只有文字描述，没有提供图片或改图意图：走文生图
- 用户提供了图片、图片链接，或明确说“改图 / 编辑这张图 / 参考这张图”：走图生图
标准调用顺序
文生图
POST /api/open/text2image/tasksGET /api/open/text2image/tasks/{taskId}，每 5 秒轮询一次- 状态
completed时展示resultUrls
图生图
- 如果用户给的是本地图片或附件：
POST /api/open/uploads/image - 从上传响应中读取
downloadUrl POST /api/open/image2image/tasks- 请求体中使用
referenceUrl = downloadUrl GET /api/open/image2image/tasks/{taskId}，每 5 秒轮询一次- 状态
completed时展示resultUrls
API 参考
Base URL: https://www.picflex.app
1. 上传图片
POST /api/open/uploads/image
- Content-Type:
multipart/form-data - 字段：
file
返回字段：
fileUrldownloadUrl
图生图使用规则：
- 如果来源是本地图片或对话附件，后续创建图生图任务时应优先使用上传接口返回的
downloadUrl - 不要把本地文件路径直接传给
referenceUrl - 如果上传接口同时返回
fileUrl和downloadUrl，优先使用downloadUrl
2. 创建文生图任务
POST /api/open/text2image/tasks
常用字段：
promptmodelaspectRatioresolutionoutputFormatnegativePrompt
返回字段：
taskIdstatusrequiredCreditsavailableCreditsreservedCreditsspendableCredits
3. 查询文生图任务
GET /api/open/text2image/tasks/{taskId}
4. 创建图生图任务
POST /api/open/image2image/tasks
常用字段：
referenceUrl或referenceUrlspromptmodelratioresolutionoutputFormat
返回字段：
taskIdstatusrequiredCreditsavailableCreditsreservedCreditsspendableCredits
图生图入参规则：
- 本地图片或附件：先上传，再把上传响应里的
downloadUrl传入referenceUrl - 公网图片 URL：可直接传入
referenceUrl - 多张本地图片：逐张上传，拿到多个
downloadUrl后传入referenceUrls
5. 查询图生图任务
GET /api/open/image2image/tasks/{taskId}
任务状态说明
queued: 已提交，等待执行processing: 执行中completed: 已完成，可读取resultUrlsfailed: 失败，查看failCode和failMessage
结果展示要求
- 成功时严格使用下面的固定格式，不要改成项目符号列表：
生成好了。
模型：`{model}`
状态：`{status}`
消耗积分：`{consumedCredits}`
任务 ID：`{taskId}`
图片 URL：
{resultUrl}
- 如果有多张图，保留前 4 行摘要不变，然后按下面格式逐张输出：
图片 1 URL：
{resultUrl1}
图片 2 URL：
{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 的横版封面” -> 图生图