AICore Docs图像API接口
Retouch (人物美颜)
智能人像美化处理API接口，提供专业的人像美颜功能，能够自动识别人脸并进行智能优化，包括皮肤光滑、色调调整、五官优化等多种美颜效果
📋 基本信息
| 属性 | 值 |
|---|---|
| 接口地址 | POST /v1/chat/completions |
| 模型名称 | retouch |
📝 请求参数
| 路径 | 参数 | 类型 | 必填 | 说明 | 默认 |
|---|---|---|---|---|---|
| - | model | string | ✅ | 模型名称，固定为 retouch | - |
| - | messages | array | ✅ | 消息数组，包含用户输入的文本和图片 | - |
| - | extra_body | object | ❌ | 额外参数对象 | {} |
messages[] | role | string | ✅ | 消息角色，固定为 user | - |
messages[] | content | array | ✅ | 内容数组，包含文本和图片元素 | - |
content[] | type | string | ✅ | 内容类型：text 或 image_url | - |
content[] | text | string | ❌ | 当 type 为 text 时的文本内容 | "a person" |
content[] | image_url | object | ❌ | 当 type 为 image_url 时的图片对象 | - |
image_url | url | string | ✅ | 图片的URL地址（当type为image_url时必填） | - |
extra_body | codeformer_fidelity | number | ❌ | 修复保真度参数 (0.0-1.0) | 0.1 |
注意：retouch 模型需要一个图片来进行美颜处理。
📝 请求示例
curl https://api.xty.app/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxx" \
-d '{
"model": "retouch",
"extra_body": {
"codeformer_fidelity": 0.1
},
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "a person"},
{
"type": "image_url",
"image_url": {
"url": "https://image.xty.app/mgxm/a11098b0-a18a-4c02-a19a-9a7045d68426/010.jpg"
}
}
]
}
]
}'import requests
import json
url = "https://api.xty.app/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer sk-xxxxx"
}
data = {
"model": "retouch",
"extra_body": {
"codeformer_fidelity": 0.1
},
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "a person"},
{
"type": "image_url",
"image_url": {
"url": "https://image.xty.app/mgxm/a11098b0-a18a-4c02-a19a-9a7045d68426/010.jpg"
}
}
]
}
]
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())from openai import OpenAI
import httpx
client = OpenAI(
base_url="https://api.xty.app/v1",
api_key="sk-xxxxx",
http_client=httpx.Client(
base_url="https://api.xty.app/v1",
follow_redirects=True,
),
)
response = client.chat.completions.create(
model="retouch",
extra_body={
"codeformer_fidelity": 0.1
},
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "a person"},
{
"type": "image_url",
"image_url": {
"url": "https://image.xty.app/mgxm/a11098b0-a18a-4c02-a19a-9a7045d68426/010.jpg"
}
}
]
}
]
)
print(response)fetch('https://api.xty.app/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer sk-xxxxx'
},
body: JSON.stringify({
model: "retouch",
extra_body: {
codeformer_fidelity: 0.1
},
messages: [
{
role: "user",
content: [
{type: "text", text: "a person"},
{
type: "image_url",
image_url: {
url: "https://image.xty.app/mgxm/a11098b0-a18a-4c02-a19a-9a7045d68426/010.jpg"
}
}
]
}
]
})
})
.then(response => response.json())
.then(data => console.log(data));📤 响应示例
成功响应
{
"id": "xty-1704067200000",
"object": "chat.completion",
"created": 1704067200,
"model": "retouch",
"choices": [
{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "https://file.xty.app/docs/retouch.png"
}
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0
}
}错误响应
{
"error": {
"message": "retouch模型需要图片，请在请求中包含图片",
"type": "invalid_request_error",
"param": null,
"code": null
}
}🖼️ 效果展示
输入示例
输入文字：请对这张图片进行美颜处理
输入图片：
参数设置：codeformer_fidelity = 0.1
输出结果
输出图片：
🎨 参数说明
codeformer_fidelity 参数
- 范围：0.0 - 1.0
- 默认值：0.1
- 说明：控制修复保真度，数值越高保真度越高，但可能保留更多原始瑕疵
- 推荐值：
0.1：轻度修复，适合日常使用0.3：中度修复，平衡效果和保真度0.5：较强修复，适合需要明显改善的图片
💡 使用技巧
图片质量要求
- 清晰度：使用高分辨率、清晰的图片
- 人脸可见：确保人脸清晰可见，光线均匀
- 正面角度：正面或微侧面效果最佳
最佳实践
- 参数调节：根据图片质量调整
codeformer_fidelity值 - 光线条件：选择光线均匀的照片
- 人脸大小：人脸在图片中占据适当比例
⚠️ 注意事项
- 图片要求：必须包含清晰可识别的人脸
- 图片格式：支持通过URL和base64提供的图片，格式包括 JPEG、PNG、WebP 等
- 处理时间：根据图片复杂度，处理时间在10-30秒之间
- 文件大小：建议每张图片不超过 10MB
- 参数类型：
codeformer_fidelity必须是数字类型，不能是字符串 - URL有效期：返回的图像URL地址有效期为1个小时，请及时保存或下载