把照片变得更好看-万维易源

概述

把照片变得更好看

任务目标

• 基于用户上传的原始照片，自动完成合规校验、主体视觉分析、提示词融合与高清重绘，输出媲美专业摄影后期的高品质成片
• 具备输入合规校验优化、照片主体视觉分析与特征提取、提示词智能组装融合、高清图像生成、生成状态轮询能力
• 触发场景：人像照片精修、照片美化、宠物/商品图优化、风景照画质增强、图像再创作

能力组成

能力流程描述

本技能由 5 个能力节点串行协作完成，整体链路如下：

1. 合规校验优化（step_0_prompt_guardian）：对用户上传的照片与生成意图进行合规性校验与优化，拦截违规内容，保证后续生成安全可控。
2. 照片主体视觉分析与特征提取（step_1_analyze_photo）：视觉模型分析图中是否存在显著主体（人物/动物/物品）。若存在，详细描述主体特征（如脸型、发型、情绪、姿态、朝向）；若不存在，描述整体场景和背景特征；同时评估画面中是否存在干扰项，产出结构化分析结果（structured_analysis）。
3. 提示词智能组装与融合（step_2_fuse_prompt）：接收上一步的结构化分析结果，与固定画质优化模板进行智能组装与融合，生成针对该照片的定制化生图提示词。
4. 启动高清图像生成任务（step_3_start_image_task）：以原始照片作为参考图（referImages），携带融合后的提示词与用户指定宽高比（aspect_ratio），调用默认高清生图引擎启动生成任务。
5. 轮询图像生成状态（step_4_poll_image_status）：每 5 秒轮询一次生成任务状态，最长等待 1200 秒，直至任务状态为 SUCCEEDED，输出最终成片。

数据流转方式：photo_image 与 aspect_ratio 作为技能入参注入 → 合规校验通过后进入视觉分析 → 结构化分析结果（structured_analysis）流入提示词融合节点 → 融合后提示词 + 原始照片参考图 + 宽高比共同流入生图节点 → 轮询节点持续跟踪生成状态 → 最终输出 result（优化后图片 URL）与 prompt（融合后生图提示词）。

人机协作节点：用户需提供原始照片（标准 Base64 编码字符串或合法可访问的 URL，支持 JPG/PNG/WebP），可选指定输出宽高比；任务异步执行期间，用户通过轮询接口逐步获取任务进度，任务完成后取得成片与提示词。

技能能力组成流程图

flowchart TD
    A["用户输入<br/>photo_image：原始照片（Base64/URL）<br/>aspect_ratio：宽高比（默认1:1）"] --> B["step_0 合规校验优化<br/>prompt_guardian"]
    B -- "校验通过" --> C["step_1 照片主体视觉分析与特征提取<br/>photo_subject_analyzer"]
    B -- "校验不通过" --> Z["流程终止，返回合规错误"]
    C -- "structured_analysis 结构化分析结果" --> D["step_2 提示词智能组装与融合<br/>image_prompt_fuser"]
    D -- "融合后生图提示词" --> E["step_3 启动高清图像生成任务<br/>参考图=原始照片 · 默认引擎"]
    E --> F["step_4 轮询图像生成状态<br/>间隔5s · 超时1200s"]
    F -- "task_status === 'SUCCEEDED'" --> G["技能输出<br/>result：优化成片URL<br/>prompt：生图提示词"]
    F -- "生成中，继续轮询" --> F
    F -- "超时/失败" --> H["返回失败信息"]

官方流程图参考：

前置准备

• 凭证：配置 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 获取后请妥善保存，避免重复验证
• 接口信息：
  • 工作流编码：smart-photo-optimization（flow_id：6a8e87753c51f24167012180）
  • 任务执行接口：POST https://route.showapi.com/flow/execute/6a8e87753c51f24167012180（JSON 请求体）
  • 任务查询接口：GET https://route.showapi.com/flow/task/query/{task_id}
  • 鉴权方式：URL 查询参数携带 appKey={你的AppKey}
  • 请求/响应格式：JSON
• 照片要求：原始照片需为标准 Base64 编码字符串或合法可访问的 URL，支持 JPG/PNG/WebP 格式
• 模拟体验：无 appKey 时，系统自动触发模拟调用，直接返回完整结果，快速预览生成效果
• 依赖：仅使用 Python 标准库，无需安装第三方包

入参与出参

入参说明

出参说明

操作步骤

模拟体验流程（无 appKey）

1. 自动触发模拟调用

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

1. 可视化预览

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

1. 引导真实调用

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

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

1. 收集用户需求

获取用户原始照片（标准 Base64 编码字符串、合法可访问的 URL 或本地图片路径，支持 JPG/PNG/WebP），确认期望的输出宽高比（可选，默认 1:1）。

1. 异步提交生成任务

调用脚本异步执行照片分析、提示词融合与高清生图任务，仅返回唯一 task_id，不阻塞等待。调用示例：

   python scripts/execute_task.py --photo-image "https://oss.showapi.com/doc/4888/163/2420f0e1f171_1787724448516.jpg?x-oss-process=image/resize,p_100" --aspect-ratio 1:1 --async

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

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

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

1. 等待结果完成

必须轮询直到完成。

1. 结果解析与落地应用

提取 result（最终优化生成的图片 URL）与 prompt（智能组装融合后的生图提示词），可将原图与成片对比展示，或基于提示词微调后二次生成。

1. 生成html页面

生成一个简单的 html 页面来融合返回的主要信息，特别是图片（建议呈现原图与优化成片的前后对比）。

使用示例

示例1：人像照片精修

• 输入：一张人像照片 URL，期望输出 3:4 竖版精修图
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：保留面部特征与神态、优化肤色光影与背景景深的高品质人像成片 + 对应生图提示词
• 配置要点：aspect_ratio=3:4

示例2：宠物/商品图优化

• 输入：宠物照片或商品物品照片（本地图片路径或 Base64 编码字符串）
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：主体特征增强、背景净化、细节质感提升的优化成片
• 配置要点：aspect_ratio 可选 1:1 或 4:3

示例3：风景照画质增强

• 输入：无显著主体的风景/场景照片
• 流程：异步提交任务 → 获取task_id → 轮询查询（每轮反馈进度/数据）
• 产出：整体场景与背景特征优化、画质增强的高清成片
• 配置要点：aspect_ratio 可选 16:9

生成效果示例

描述

技能运行完成后输出两大部分内容：

1. prompt（生图提示词）：系统根据照片主体/场景特征智能组装并融合固定模板后的提示词，包含主体描述（脸型、发型、情绪、姿态、朝向，或整体场景与背景特征）、光影氛围与画质优化方向等信息；
2. result（优化成片 URL）：最终高清优化图片的访问地址，可直接下载或嵌入页面展示。

可视化呈现方式：建议以「原图 → 优化成片」前后对比的形式展示，并附上提示词文本，方便理解优化思路与进行二次调整。

输出案例

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

优化成片效果示例图：

接口返回 JSON 形态示例（以下为示例数据，实际以接口返回为准）：

{
  "showapi_res_body": {
    "task_status": "SUCCEEDED",
    "result": "https://oss.showapi.com/workflow-output/6a8e87753c51f24167012180/optimized_9f8e7d6c5b.png",
    "prompt": "以原图为基础，保留人物面部特征、发型与神态，优化肤色质感与光线层次，柔化背景杂乱细节并增强景深虚化，提升整体清晰度、色彩通透感与影调氛围，8K超高清画质，专业摄影后期精修质感"
  },
  "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",
    "result": "最终优化生成的高品质图片访问地址（任务完成时返回）",
    "prompt": "系统根据照片特征智能组装并融合固定模板后的生图提示词（任务完成时返回）"
  },
  "showapi_res_code": 0,
  "showapi_fee_num": 1
}

异常说明

注意事项

1. photo_image 为必填项，需传入标准 Base64 编码字符串或合法可访问的 URL，支持 JPG/PNG/WebP 格式。
2. aspect_ratio 为可选项，默认 1:1，可选值：1:1、3:4、4:3、16:9、9:16。
3. 所有任务强制异步执行，不支持同步模式。
4. 轮询查询过程中，每次获取接口返回数据后，立即将主要内容反馈给用户。
5. 工作流内部生图轮询间隔 5 秒、最长等待 1200 秒，请耐心等待直至任务完成。
6. 本技能预估 0.22 元/次，实际计费按输出内容消耗 token 多少有所浮动。
7. 模拟运行说明：无 appKey 时系统自动触发模拟调用，一次性返回完整 JSON 结果，不经过 execute_task.py 和 query_task.py，结果仅作效果预览，非真实生成内容。如需真实调用，请通过手机验证获取 AppKey 并配置。