拼豆图纸生成-万维易源

概述

拼豆图纸生成

任务目标

• 根据用户提供的实物图片，自动生成可直接落地的拼豆图纸，免去手工取色与绘图
• 具备输入合规校验、视觉理解分析、专业提示词生成、图纸绘制、生成状态轮询能力
• 触发场景：手工拼豆图纸制作、IP形象/文创周边图纸化、亲子手工设计、像素画与图像创作（life_craft、image_creation）

能力组成

能力流程描述

本技能以「实物图片（URL 或 Base64，必填）+ 设计指导（可选）+ 图纸宽高比（可选，默认 1:1）」为输入，经五个阶段串行处理，最终输出拼豆图纸图片 URL 及配套提示词信息：

1. 合规校验优化（阶段1）：对用户输入的图片与设计指导进行合规校验与优化，过滤违规内容，保证生成输入安全合规；校验不通过则终止流程并返回提示。
2. 视觉理解分析（阶段2）：深度分析图片，提取主体对象与姿态、主要颜色及占比（按面积从大到小排列）、轮廓特征（硬边缘/柔边缘）、细节复杂度（适合初学者简化还是保留细节），输出结构化分析结果。
3. 专业提示词生成（阶段3）：将阶段2的视觉分析结果与用户设计指导进行语义约束融合（融合策略：semantic_constraint_fusion；优先级规则：拼豆工艺约束 > 设计指导 > 视觉细节），生成用于图纸绘制的正向提示词与反向提示词。
4. 生成拼豆图纸（阶段4）：以原图为参考图，结合正向提示词与用户指定的宽高比，调用图像生成能力绘制网格化拼豆图纸。
5. 轮询图纸生成状态（阶段5）：以 5 秒间隔轮询图纸生成任务状态，最长等待 1200 秒，直至 task_status 为 SUCCEEDED，返回拼豆图纸 URL。

数据流转方式：图片在阶段1参与合规校验、在阶段4作为参考图；阶段2输出的视觉分析摘要与结构化特征流入阶段3，作为提示词生成的核心依据；阶段3生成的正向提示词流入阶段4驱动图纸绘制；阶段4的生成结果由阶段5轮询确认，最终汇聚输出图纸URL、正向/反向提示词与视觉分析摘要。人机协作节点：用户可通过设计指导（如"适合初学者""颜色不超过5种"）控制图纸复杂度与用色数量，也可指定宽高比适配不同拼豆底板规格。

技能能力组成流程图

flowchart TD
    A["用户输入<br/>img_url 实物图片（必填）<br/>design_guidance 设计指导（可选）<br/>aspect_ratio 宽高比（可选，默认1:1）"] --> B["阶段1 合规校验优化"]
    B -->|校验通过| C["阶段2 视觉理解分析<br/>提取主体/颜色占比/轮廓/细节复杂度"]
    B -->|校验不通过| X["流程终止，返回合规提示"]
    C --> D["阶段3 专业提示词生成<br/>视觉结果+设计指导语义融合"]
    D --> E["阶段4 生成拼豆图纸<br/>原图+正向提示词+宽高比"]
    E --> F["阶段5 轮询生成状态<br/>间隔5秒/超时1200秒"]
    F -->|task_status = SUCCEEDED| G["最终输出<br/>pattern_image_url 图纸URL<br/>positive_prompt / negative_prompt<br/>visual_analysis_summary"]
    F -->|超时或失败| X

实际能力流程图：

前置准备

• 凭证：配置 ShowAPI AppKey，凭证名称：showapi_appkey
• 鉴权配置：

本 Skill 调用需要 AppKey 鉴权。所有 API 请求的 URL 查询参数中需携带 appKey={你的AppKey}。

如何获取 AppKey

如果你还没有 AppKey，请按以下步骤通过手机验证获取：

1. 请用户提供手机号（中国大陆手机号）
2. 调用发送验证码接口：

“` POST https://www.showapi.com/auth/agent_sendCode Content-Type: application/x-www-form-urlencoded

phone={手机号} “ 成功响应：{"flag":true,"remark":"发送成功"}`

1. 请用户查看手机收到的6位验证码并告诉你
2. 调用验证接口获取 AppKey：

“` POST https://www.showapi.com/auth/agent_verify Content-Type: application/x-www-form-urlencoded

phone={手机号}&code={验证码} “ 成功响应：{"flag":true,"app_key":"你的AppKey"}`

1. 将获取到的 app_key 保存，后续所有 API 调用 URL 中携带 appKey={app_key} 参数

注意事项

• 验证码5分钟有效，每分钟只能发送1次
• 如果手机号已注册过易源数据平台账户，会直接返回该账户的 AppKey，不会重复注册
• AppKey 获取后请妥善保存，避免重复验证
• 模拟体验：无 appKey 时，系统自动触发模拟调用，直接返回完整结果，快速预览生成效果
• 依赖：仅使用 Python 标准库，无需安装第三方包

操作步骤

模拟体验流程（无 appKey）

1. 自动触发模拟调用

系统检测到未配置 appKey 时，自动向 https://www.showapi.com/_nuxt3/api/2405-105 发送 POST 请求（body: {"flow_id":"6a793ccf3c51f2ec21031667"}），直接获取完整模拟生成结果。此过程为一次性返回，不执行 execute_task.py 和 query_task.py。

1. 可视化预览

将返回的 JSON 结果以 HTML 形式可视化展示，重点呈现拼豆图纸图片内容。

1. 引导真实调用

提示用户当前为无 appKey 的模拟运行结果。如需真实调用，请通过手机验证获取 AppKey（步骤见「前置准备-鉴权配置」），并在后续所有 API 调用 URL 中携带 appKey={app_key} 参数。

标准流程（有 appKey，强制异步执行）

1. 收集用户需求

确认实物图片（URL 或 Base64，必填）、设计指导（如"适合初学者""颜色不超过5种"，选填）、图纸宽高比（选填，默认 1:1，可选 1:1、3:4、4:3、16:9、9:16）。

1. 异步提交生成任务

调用脚本异步执行视觉分析、提示词生成与图纸绘制任务，仅返回唯一 task_id，不阻塞等待。调用示例（图片 URL 方式）：

   python scripts/execute_task.py --img-url "https://example.com/toy.png" --design-guidance "适合初学者，颜色不超过8种" --aspect-ratio 1:1 --async

调用示例（本地文件方式，适合较长的 Base64 字符串）：

   python scripts/execute_task.py --img-file img_b64.txt --aspect-ratio 3:4 --async

1. 轮询查询任务结果（必选）

使用 task_id 循环查询任务状态，每一轮轮询后，即时将当前返回的核心资料同步反馈给用户，直至 task_status 为 SUCCEEDED 获取完整结果。调用示例：

   python scripts/query_task.py --task-id "返回的task_id值"

1. 等待结果完成

必须轮询直到完成（图纸生成耗时较长，内部轮询最长 1200 秒、间隔 5 秒，请耐心等待）。

1. 结果解析与落地应用

提取拼豆图纸 URL（pattern_image_url），结合视觉分析摘要（visual_analysis_summary）核对色彩与细节还原度；正向/反向提示词可微调后复用于生成同类图纸。

1. 生成html页面

生成一个简单的html页面来融合返回的主要信息，特别是拼豆图纸图片（支持点击放大查看网格细节）。

使用示例

示例1：卡通玩偶图纸制作

• 输入：一张卡通玩偶照片 + 宽高比 1:1
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：玩偶拼豆图纸 + 视觉分析摘要 + 正向/反向提示词
• 配置要点：img_url 传图片URL，aspect_ratio=1:1，适合方形标准底板

示例2：初学者简化版图纸

• 输入：实物图片 + 设计指导“适合初学者，颜色不超过5种”
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：低复杂度、少色数的简化版拼豆图纸
• 配置要点：design_guidance 明确约束颜色数量与难度，便于儿童或新手拼搭

示例3：横幅/立幅场景图纸

• 输入：场景类实物图片 + 宽高比 16:9（横幅）或 9:16（立幅）
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：适配异形底板规格的拼豆图纸
• 配置要点：aspect_ratio 按底板规格选择，可搭配设计指导约束背景复杂度

生成效果示例

描述

运行成功后，技能输出四项核心内容：

• 拼豆图纸URL（pattern_image_url）：生成的网格化拼豆图纸图片地址，色块对应拼豆色号分区，可下载放大打印用于拼豆拼搭
• 视觉分析摘要（visual_analysis_summary）：原图的主体对象与姿态、主要颜色及占比、轮廓特征、细节复杂度分析结论，便于核对图纸还原度
• 正向提示词（positive_prompt）：用于生成图纸的正向约束提示词，可微调后复用于同类图纸生成
• 反向提示词（negative_prompt）：用于排除照片写实、渐变过渡、复杂背景等不符合拼豆工艺特征的排除项

可视化呈现方式：将结果渲染为 HTML 页面，并排展示视觉分析摘要与拼豆图纸大图，图片支持点击放大查看网格细节。

输出案例

说明：若输出结果包含图片，优先插入对应图片资源，之后再输出 JSON / Markdown 格式的文本内容。

拼豆图纸生成效果示例图：

接口返回 JSON 示例（任务查询最终轮返回数据，展示接口返回数据的实际形态）：

{
  "showapi_res_body": {
    "task_status": "SUCCEEDED",
    "visual_analysis_summary": "主体对象为一只坐姿卡通小熊玩偶，头部微倾；主要颜色按面积占比从大到小依次为：棕色约45%、米白色约30%、深褐色约15%、黑色约10%；轮廓以柔边缘为主，四肢与身体分界圆润；细节复杂度中等，五官区域细节较多，建议图纸上保留细节以保证还原度，整体适合按色区分区拼搭。",
    "positive_prompt": "拼豆图纸设计，卡通小熊坐姿像素图案，主色棕色、米白色、深褐色、黑色，色块分明，网格化排布，边缘圆润，保留五官细节，居中构图，纯色背景",
    "negative_prompt": "照片写实、渐变色彩、复杂背景、阴影过渡、模糊轮廓、色块断裂、超出常规拼豆色板数量",
    "pattern_image_url": "https://showapi-pub-hangzhou.oss-cn-hangzhou.aliyuncs.com/huangye/perler_beads_pattern_demo.png"
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

资源索引

• [scripts/execute_task.py](scripts/execute_task.py)：异步提交拼豆图纸生成任务（真实调用时使用）
• [scripts/query_task.py](scripts/query_task.py)：轮询查询异步任务结果（真实调用时使用）

响应数据结构

1. 异步任务提交响应

{
  "showapi_res_body": {
    "task_id": "唯一任务ID",
    "status": "pending",
    "msg": "任务已提交，正在异步处理中"
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

2. 任务查询响应（单轮轮询返回数据，需实时同步给用户）

{
  "showapi_res_body": {
    "task_status": "SUCCEEDED",
    "visual_analysis_summary": "原图视觉分析结果摘要",
    "positive_prompt": "生成的正向提示词",
    "negative_prompt": "生成的反向提示词",
    "pattern_image_url": "生成的拼豆图纸图片URL"
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

说明：轮询过程中若任务尚未完成，task_status 为 PENDING/RUNNING 等中间状态，且可能不含 pattern_image_url 等最终字段；需持续轮询直至 task_status 为 SUCCEEDED。

注意事项

1. img_url 为必填项，支持实物图片的 URL 或 Base64 编码字符串；使用 Base64 时内容较长，建议通过 execute_task.py 的 –img-file 参数从本地文件读取。
2. 所有任务强制异步执行，不支持同步模式。
3. 轮询查询过程中，每次获取接口返回数据后，立即将主要内容反馈给用户。
4. 图纸生成属于图像生成任务，耗时较长（内部轮询间隔 5 秒、最长 1200 秒），请耐心等待，轮询至 task_status 为 SUCCEEDED。
5. aspect_ratio 可选值为 1:1、3:4、4:3、16:9、9:16，默认 1:1，建议根据拼豆底板规格选择。
6. design_guidance 为选填项，可输入“适合初学者”“颜色不超过5种”等约束，帮助控制图纸复杂度与用色数量。
7. 单次调用预估费用约 0.22 元（含模型推理价格），实际以平台计费为准。
8. 模拟运行说明：无 appKey 时系统自动触发模拟调用，一次性返回完整 JSON 结果，不经过 execute_task.py 和 query_task.py，结果仅作效果预览，非真实生成内容。如需真实调用，请通过手机验证获取 AppKey 并配置。