---
name: yunxiu-imagerender-pro
description: "使用云修 OpenAPI 提交异步修图任务、轮询结果，并支持预设 ID、原始参数、素材 ID 与结构化参数拼装。触发词包括但不限于：云修 API、云修OpenAPI、预设ID、media_code、chain task、修图、修图参数、P图、精修、图片精修、图片处理、人像美化、人像精修、瘦脸、瘦腿、瘦身、美颜、磨皮、美白、提亮、美白牙齿、祛痘、祛斑、祛皱、祛眼袋、祛黑眼圈、祛双下巴、大眼、亮眼、丰唇、瘦鼻、瘦脸、V脸、小脸、美型、美妆、妆容、滤镜、调色、色彩调整、白平衡、曝光、对比度、饱和度、锐化、清晰度、去雾、换天空、换背景、证件照、瘦腿瘦身、素材 ID、query.json、preview_chain、chain.json、图片格调、影调、色温、质感磨皮、发色、肤色、腮红、眼影、眉毛、睫毛、唇彩、修容、美瞳、卧蚕。支持完整参数目录与素材目录查询，但不支持整妆素材。"
license: Proprietary. See LICENSE.
compatibility: Requires Python 3, network access to openapi-yunxiu.meitu.com, and ~/.meitu/credentials.json only for submit operations.
metadata:
  version: "3.0.0"
  parameter_version: "7.7.0"
  source_revision: "940"
---

# 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` 处理：

| `semantic_type` | 规则 |
|---|---|
| `people-int-list` | 5 个整数，固定人群顺序 |
| `people-string-list` | 5 个字符串，固定人群顺序 |
| `people-material-list` | 5 个 schema 定义的素材对象，固定人群顺序 |
| `curve-points` | 扁平化 x/y 坐标对，至少 4 项且长度为偶数 |
| `rgba` | 恰好 4 个整数通道 |
| `object` / `list<object>` | 只按 schema 的字段、类型、必填项和长度约束处理 |

固定人群顺序是 `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 值为：

```json
[
  {"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": ""}
]
```

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

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

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

### Execute

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

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

预览模式：

```bash
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

查询已有任务：

```bash
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 校验。查询接口可独立排查：

```bash
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

预设模式：

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

原始参数模式：

```json
{
  "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`