Agent Skill

拼豆图纸生成-万维易源

根据实物图片一键生成专业拼豆图纸;自动分析图片主体、色彩占比、轮廓与细节复杂度,生成正向/反向提示词并绘制网格图纸;适用于手工拼豆图纸制作、IP形象图纸化、亲子手工、像素画设计与图像创作场景

设计多媒体·万维易源·来自 skill_hub·skillhub.cn ↗
skillhub install @showapi/perler-beads-pattern-generation-showapi
2 Stars·5.2万 综合热度·6,153 字文档·源站更新 2026-11-18

README 文档

6,153 字

拼豆图纸生成

任务目标

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

能力组成

能力流程描述

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

  1. 合规校验优化(阶段1):对用户输入的图片与设计指导进行合规校验与优化,过滤违规内容,保证生成输入安全合规;校验不通过则终止流程并返回提示。
  2. 视觉理解分析(阶段2):深度分析图片,提取主体对象与姿态、主要颜色及占比(按面积从大到小排列)、轮廓特征(硬边缘/柔边缘)、细节复杂度(适合初学者简化还是保留细节),输出结构化分析结果。
  3. 专业提示词生成(阶段3):将阶段2的视觉分析结果与用户设计指导进行语义约束融合(融合策略:semanticconstraintfusion;优先级规则:拼豆工艺约束 > 设计指导 > 视觉细节),生成用于图纸绘制的正向提示词与反向提示词。
  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. 将获取到的 appkey 保存,后续所有 API 调用 URL 中携带 appKey={appkey} 参数

注意事项

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

操作步骤

模拟体验流程(无 appKey)

  1. 自动触发模拟调用

系统检测到未配置 appKey 时,自动向 https://www.showapi.com/nuxt3/api/2405-105 发送 POST 请求(body: {"flowid":"6a793ccf3c51f2ec21031667"}),直接获取完整模拟生成结果。此过程为一次性返回,不执行 executetask.py 和 querytask.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. 轮询查询任务结果(必选)

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

   python scripts/query_task.py --task-id "返回的task_id值"
  1. 等待结果完成

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

  1. 结果解析与落地应用

提取拼豆图纸 URL(patternimageurl),结合视觉分析摘要(visualanalysissummary)核对色彩与细节还原度;正向/反向提示词可微调后复用于生成同类图纸。

  1. 生成html页面

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

使用示例

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

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

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

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

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

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

生成效果示例

描述

运行成功后,技能输出四项核心内容:

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

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

输出案例

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

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

拼豆图纸生成效果示例1

拼豆图纸生成效果示例2

拼豆图纸生成效果示例3

接口返回 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/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
}

说明:轮询过程中若任务尚未完成,taskstatus 为 PENDING/RUNNING 等中间状态,且可能不含 patternimageurl 等最终字段;需持续轮询直至 taskstatus 为 SUCCEEDED。

注意事项

  1. imgurl 为必填项,支持实物图片的 URL 或 Base64 编码字符串;使用 Base64 时内容较长,建议通过 executetask.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 结果,不经过 executetask.py 和 querytask.py,结果仅作效果预览,非真实生成内容。如需真实调用,请通过手机验证获取 AppKey 并配置。

同分类其他技能

查看全部 ›