美图云修智能修图API PRO版

概述

Yunxiu ImageRender Pro

Overview

通过云修 OpenAPI PRO 参数版本 7.7.0（飞书文档修订 940）提交异步图片处理任务，支持预设 ID、原始参数、素材型参数、结果查询与轮询。默认由 python3 scripts/yunxiu_api.py 执行 schema 校验、凭证注入、请求和输出脱敏。

Source Of Truth

• 参数决策：先查由 references/schema/parameters.json 生成的 references/pro-openapi-reference.md 与 references/params/README.md。
• 素材决策：先查由 references/schema/materials.json 生成的 references/materials-reference.md 与 references/catalogs/*.md。
• 机器校验：以两个 canonical schema 和 scripts/yunxiu_schema.py 为准；不要手工推断未记录的契约。
• 凭证：仅从 ~/.meitu/credentials.json 加载。请求示例和 fixture 不含 api_key 或 api_secret。

Strict Constraints

参数与素材白名单

1. all_params 的键必须存在于当前参数 schema。未知键和已移除键即使由用户显式提供也必须拒绝，不得透传、改名猜测或回退到旧版本。
2. 参数类型、语义类型、范围、对象字段和状态必须与生成引用一致。
3. 素材 ID、颜色和适用参数必须存在于生成素材引用，禁止从名称猜 ID 或跨参数复用 ID。
4. 如果结构标记为 status: unverified，禁止根据自然语言合成。用户显式提供 JSON 时，也只能采用 schema 已记录的候选策略并通过 runner 校验；没有候选策略则拒绝。
5. 整妆素材不支持。用户请求一键整妆时，可以建议拆成眉毛、眼影、眼线、睫毛、修容、高光、腮红、唇彩等已支持子素材，但绝不能发明整妆字段。

列表与结构语义

不能把所有 list 当成五个整数。按参数的 semantic_type 处理：

固定人群顺序是 man、woman、child、oldwoman、oldman。只有 schema 标为 people list 的参数使用该五人顺序。

Core Workflow

Preflight

1. 判断模式：
   • 给出 chain_id 或要求查状态：query
   • 给出 media_code：preset
   • 给出参数 JSON、素材组合或明确修图需求：raw-params
2. 图片必须是公网 HTTP/HTTPS URL，不支持 IP 地址、base64 或本地路径；路径扩展名必须为 jpg、jpeg 或 png。
3. 正式提交默认使用 chain.json。只有用户明确要求预览且图片应不超过 1500x1500 时使用 --preview；runner 不解析、下载或探测图片 URL，尺寸与可用性由云修 OpenAPI 服务端校验并拒绝不合规输入。
4. 参数或素材决策必须先查生成引用。自然语言无法映射到当前、已验证结构时，说明不支持或要求用户提供符合候选策略的显式 JSON，不要猜测。

Resolve And Validate

1. 请求中 media_code 与 parameter 必须恰好出现一个，不能同时提交。
2. 用户显式 JSON 只保留值和仍属当前 schema 的精确键；runner 校验失败就停止，不得因为键由用户提供而绕过错误。
3. 算法测已内置 people_type 参数，用户侧请求体无需传 people_type，算法侧内置的 people_type 值为：

[
  {"age": [15, 49], "gender": 1, "key": "man", "name": ""},
  {"age": [15, 49], "gender": 0, "key": "woman", "name": ""},
  {"age": [0, 14], "gender": 0, "key": "child", "name": ""},
  {"age": [50, 100], "gender": 0, "key": "oldwoman", "name": ""},
  {"age": [50, 100], "gender": 1, "key": "oldman", "name": ""}
]

1. 对 people list，默认只在目标人群位置填激活值，其余位置使用 schema 允许的非激活值。素材对象的字段和值必须按生成引用处理，不能假定每种素材都有颜色。
2. 曲线使用扁平坐标对；RGBA 使用四通道；filter、sky_background 及其他对象严格按生成的结构体字段表拼装。
3. 先把无凭证请求写到 /tmp/yunxiu-imagerender-pro/，再执行离线校验：

python3 scripts/yunxiu_api.py validate --request /tmp/yunxiu-imagerender-pro/submit.json

校验错误会在网络请求前停止。不要手工删除失败参数后继续，除非用户确认改变需求。

Execute

默认通过 runner 提交并等待终态：

python3 scripts/yunxiu_api.py submit --request /tmp/yunxiu-imagerender-pro/submit.json --wait

预览模式：

python3 scripts/yunxiu_api.py submit --request /tmp/yunxiu-imagerender-pro/submit.json --preview --wait

预览图片应不超过 1500x1500。runner 只做请求 schema 校验、凭证注入和 API 调用，不会 inspect/fetch media_data；超尺寸或服务端无法处理的图片由云修服务返回错误。

runner 从 ~/.meitu/credentials.json 注入凭证。请求文件不得包含凭证；缺失凭证时停止并提示配置该文件。

Query

查询已有任务：

python3 scripts/yunxiu_api.py query --chain-id '<chain_id>'

submit --wait 按 2s, 2s, 3s, 3s, 4s, 4s, 5s... 最多轮询 30 次。waiting、processing 和 error_code=29901 继续等待；90024 只额外重试一次；终态错误和超时保留安全的 chain_id、状态和错误字段。

curl Troubleshooting Fallback

curl 只用于排查 HTTP、代理或服务端响应，不是默认执行路径。原始参数提交不得用 curl 绕过 runner 校验。查询接口可独立排查：

curl -sS -X POST 'https://openapi-yunxiu.meitu.com/openapi/query.json' 
  -H 'Content-Type: application/json' 
  --data '{"chain_id":"<chain_id>"}'

不得把凭证写入仓库文件、fixture、日志或命令历史。

Deliver

向用户返回：

• 本次模式：preset / raw-params / query
• 请求接口：chain.json / preview_chain.json / query.json
• chain_id 与处理状态
• 成功时的 result_url、result_url_backup 和 runner 返回的 results（如有）
• 原始参数模式的关键参数摘要，不倾倒超长 JSON
• 失败时 runner 返回的安全错误类型、状态和可继续查询的 chain_id

Credential-free Request Examples

预设模式：

{
  "media_code": "<media_code>",
  "media_data": "https://images.example.com/portrait.jpg"
}

原始参数模式：

{
  "media_data": "https://images.example.com/portrait.jpg",
  "parameter": {
    "all_params": {
      "double_chin": [0, 50, 0, 0, 0],
      "gray_point": [0, 0, 220, 188, 255, 255],
      "id_photo_bg_color": [255, 255, 255, 255]
    }
  }
}

Reference-only Use

如果不能执行 Python，仍可回答参数、结构、素材和错误码问题，但必须引用生成文档，不得声称请求已校验或提交：

• references/pro-openapi-reference.md
• references/params/README.md
• references/materials-reference.md
• references/catalogs/*.md