发型设计-万维易源

概述

发型设计师（9宫格发型设计预览图生成）

任务目标

• 基于用户上传的人物肖像底图，生成一套统一形象的多宫格（3×3）发型设计预览图
• 自动将9宫格合成大图按比例分割为9张独立发型设计图，便于逐款查看与选用
• 支持自定义成品图宽高比、宫格内简体中文文字标注（发型名称和特点）
• 触发场景：美发造型设计、发型预览推荐、理发店形象方案展示、AI试发型换装

能力组成

能力流程描述

该技能以一张人物肖像底图（portrait_image）为核心输入，配合宽高比（aspect_ratio）与文字标注开关（need_text）两个可选参数，经过六个阶段的流水线处理，最终交付「原始底图 + 9宫格合成大图 + 9张独立发型图」三类结果：

1. 合规校验优化（step_0_prompt_guardian）：对任务输入进行合规性校验与优化，保证生成链路内容安全合规。
2. 图片安全审核（step_1_check_image_safety）：对上传的 portrait_image 进行图片内容安全审核，违规图片直接拦截，流程终止。
3. 生成发型设计提示词（step_2_generate_prompt）：基于审核通过图片的人物主体，结合构图约束（9宫格3×3、宫格之间无白线）自动生成发型设计绘图提示词；若 need_text=true，则追加约束：①文字必须为简体中文；②文字底部居中；③中文标注着装名称和特点。
4. 生成9宫格发型设计大图（step_3_generate_hairstyle_image）：将生成的提示词与原图（referImages）一并送入图像生成模型，按 aspect_ratio 指定的宽高比绘制9宫格发型设计大图。
5. 轮询发型大图生成状态（step_4_poll_image_status）：以5秒为间隔轮询图像生成任务状态，最长等待1200秒，直至任务状态为 SUCCEEDED 并取得合成大图URL。
6. 按比例分割9宫格图片（step_5_split_image）：将合成大图按3行3列（3×3）等比分割，产出9张独立发型设计图URL列表。

数据流转方式：上游步骤结果（提示词、图像URL）自动注入下游步骤参数，全程自动流转；人机协作节点为初始的底图上传与参数设定，其余环节无需人工干预。

技能能力组成流程图

flowchart TD
    A[用户输入: portrait_image 人物肖像底图<br/>aspect_ratio 宽高比 / need_text 文字标注开关] --> B[step_0 合规校验优化]
    B --> C[step_1 图片安全审核]
    C -- 审核通过 --> D[step_2 生成发型设计提示词<br/>约束: 3x3宫格无白线<br/>need_text=true 时追加简体中文标注约束]
    C -- 审核不通过 --> X[流程终止并返回错误]
    D --> E[step_3 生成9宫格发型设计大图<br/>以原图为参考图, 按宽高比绘制]
    E --> F[step_4 轮询大图生成状态<br/>间隔5秒, 最长1200秒]
    F -- SUCCEEDED --> G[step_5 按比例分割9宫格图片<br/>3行x3列等比切割]
    F -- 超时或失败 --> X
    G --> H[输出: original_image 原始底图URL]
    G --> I[输出: combined_image_url 合成大图URL]
    G --> J[输出: split_images 9张独立发型图列表]

官方能力流程图快照：技能能力组成流程图

前置准备

• 凭证：配置 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":"6a841ba13c51f2e3110047dd"}），直接获取完整模拟生成结果。此过程为一次性返回，不执行 execute_task.py 和 query_task.py。

1. 可视化预览

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

1. 引导真实调用

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

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

1. 收集用户需求

获取人物肖像底图（portrait_image，标准 Base64 编码字符串或图片URL），确认成品图宽高比（aspect_ratio）与是否需要宫格文字标注（need_text）。

1. 异步提交生成任务

调用脚本异步执行9宫格发型设计图生成任务，仅返回唯一 task_id，不阻塞等待。调用示例：

   python scripts/execute_task.py --portrait-image "https://oss.showapi.com/doc/4888/3/abf2436f03b2_1782280969907.jpg?x-oss-process=image/resize,p_100" --aspect-ratio 3:4 --need-text --async

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

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

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

1. 等待结果完成

必须轮询直到完成。

1. 结果解析与落地应用

提取 original_image（原始底图）、combined_image_url（9宫格合成大图）、split_images（9张独立发型图URL列表），用于整体预览与逐款挑选展示。

1. 生成html页面

生成一个简单的html页面来融合返回的主要信息，特别是图片。

使用示例

示例1：基础发型预览图生成

• 输入：上传一张正面人物肖像底图，生成9款发型设计预览
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：9宫格合成大图 + 9张独立发型设计图
• 配置要点：aspect_ratio=3:4，need_text 不开启（默认关闭）

示例2：带文字标注的发型方案

• 输入：为理发店客户制作带发型名称和特点说明的设计方案
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：每个宫格底部居中显示简体中文标注（发型名称和特点）的9宫格预览图
• 配置要点：need_text=true，aspect_ratio 可选 3:4 或 4:3

示例3：竖版海报风格发型展示

• 输入：制作适配手机端竖屏浏览的发型设计展示图
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：竖版9宫格发型设计大图及分割图
• 配置要点：aspect_ratio=9:16，适合短视频封面/手机海报场景

生成效果示例

描述

技能运行完成后输出三类核心内容，结构清晰、开箱即用：

1. original_image（原始底图）：上传的原始人物肖像基底图URL，作为设计基准保留；
2. combined_image_url（合成大图）：一张按指定宽高比生成的9宫格合成大图URL，同一人物统一形象展示9款不同发型设计，宫格之间无白线；开启 need_text 时，每个宫格底部居中显示简体中文标注的发型名称和特点；
3. split_images（分割图列表）：由合成大图按3×3等比分割出的9张独立发型设计图URL数组，便于逐张查看、单独选用或分发交付。

可视化呈现方式：合成大图适合整体预览与对比，分割图适合逐款展示、挑选与二次分发；建议以 HTML 页面聚合展示，图片优先呈现。

输出案例

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

生成效果示例图（9宫格发型设计预览）：

接口返回 JSON 实际形态：

{
  "showapi_res_body": {
    "original_image": "https://oss.showapi.com/xxx/original_portrait.jpg",
    "combined_image_url": "https://oss.showapi.com/xxx/combined_9grid.jpg",
    "split_images": [
      "https://oss.showapi.com/xxx/split_1.jpg",
      "https://oss.showapi.com/xxx/split_2.jpg",
      "https://oss.showapi.com/xxx/split_3.jpg",
      "https://oss.showapi.com/xxx/split_4.jpg",
      "https://oss.showapi.com/xxx/split_5.jpg",
      "https://oss.showapi.com/xxx/split_6.jpg",
      "https://oss.showapi.com/xxx/split_7.jpg",
      "https://oss.showapi.com/xxx/split_8.jpg",
      "https://oss.showapi.com/xxx/split_9.jpg"
    ]
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

资源索引

• [scripts/execute_task.py](scripts/execute_task.py)：异步提交9宫格发型设计图生成任务（真实调用时使用）
• [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": {
    "original_image": "上传的原始人物肖像底图URL",
    "combined_image_url": "生成的9宫格合成大图URL",
    "split_images": [
      "分割后的第1张独立发型设计图URL",
      "分割后的第2张独立发型设计图URL",
      "分割后的第3张独立发型设计图URL",
      "分割后的第4张独立发型设计图URL",
      "分割后的第5张独立发型设计图URL",
      "分割后的第6张独立发型设计图URL",
      "分割后的第7张独立发型设计图URL",
      "分割后的第8张独立发型设计图URL",
      "分割后的第9张独立发型设计图URL"
    ]
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

异常与错误处理说明

注意事项

1. portrait_image 为必填项，请传入清晰、正面的人物肖像基底图（标准 Base64 编码字符串或普通图片URL），图片质量直接影响生成效果。
2. 上传图片会先经过安全审核，违规图片将被拦截导致任务失败。
3. aspect_ratio 可选枚举：1:1、3:4、4:3、16:9、9:16，默认 3:4。
4. need_text=true 时，每个宫格底部居中生成简体中文标注（发型名称和特点）。
5. 图像生成耗时较长，内部轮询最长等待1200秒（每5秒一次），请耐心等待并持续轮询任务状态。
6. 所有任务强制异步执行，不支持同步模式。
7. 轮询查询过程中，每次获取接口返回数据后，立即将主要内容反馈给用户。
8. 计费说明：实际计费按输出内容消耗token多少有所浮动（参考预估单价约0.22元/次）。
9. 模拟运行说明：无 appKey 时系统自动触发模拟调用，一次性返回完整 JSON 结果，不经过 execute_task.py 和 query_task.py，结果仅作效果预览，非真实生成内容。如需真实调用，请通过手机验证获取 AppKey 并配置。