e9ceedb3bf
- 创建 /api/enhance 路由，实现图片变清晰API集成 - 在图片标注组件中添加变清晰按钮（Sparkles图标） - 在相册页面添加变清晰按钮 - 系统设置：将抠图设置改名为本地AI设置，添加变清晰API配置 - 支持同步和异步两种模式 - 自动上传到S3存储桶并保存到数据库 - 在相册和出图记录中显示处理后的图片
512 lines
13 KiB
Markdown
512 lines
13 KiB
Markdown
# RMBG-2.0 API 接口文档
|
||
|
||
## 服务信息
|
||
|
||
- **服务地址**: http://156.225.27.52:8000
|
||
- **API版本**: 2.0.0
|
||
- **模型**: RMBG-2.0 (背景移除模型)
|
||
- **框架**: FastAPI
|
||
- **API文档**: http://156.225.27.52:8000/docs
|
||
- **OpenAPI规范**: http://156.225.27.52:8000/openapi.json
|
||
- **API密钥**: 所有核心接口需要API密钥认证（详见下方认证说明）
|
||
|
||
---
|
||
|
||
## 认证方式
|
||
|
||
所有核心接口（`/rmbg/file` 和 `/rmbg/base64`）需要在请求头中添加API密钥：
|
||
|
||
**请求头**:
|
||
```
|
||
X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG
|
||
```
|
||
|
||
**注意**: 以下端点无需API密钥：
|
||
- `GET /` - 根端点（服务状态检查）
|
||
- `GET /health` - 健康检查
|
||
- `GET /api-key-info` - API密钥信息
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 根端点 - 服务状态检查
|
||
|
||
**接口地址**: `GET /`
|
||
|
||
**描述**: 检查服务是否正常运行
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl http://156.225.27.52:8000/
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"message": "RMBG-2.0 API 服务运行正常",
|
||
"version": "2.0.0",
|
||
"model": "RMBG-2.0"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 健康检查
|
||
|
||
**接口地址**: `GET /health`
|
||
|
||
**描述**: 检查服务健康状态和模型加载状态（无需API密钥）
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl http://156.225.27.52:8000/health
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"model_loaded": true,
|
||
"model": "RMBG-2.0"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. API密钥信息
|
||
|
||
**接口地址**: `GET /api-key-info`
|
||
|
||
**描述**: 获取API密钥使用说明（无需API密钥）
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl http://156.225.27.52:8000/api-key-info
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"api_key_name": "X-API-Key",
|
||
"description": "请在请求头中添加API密钥"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 文件上传背景移除
|
||
|
||
**接口地址**: `POST /rmbg/file`
|
||
|
||
**描述**: 通过文件上传方式移除图片背景（需要API密钥）
|
||
|
||
**Content-Type**: `multipart/form-data`
|
||
|
||
**请求头**:
|
||
```
|
||
X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| file | File | 是 | 图片文件（支持常见图片格式） |
|
||
|
||
**请求示例 (cURL)**:
|
||
```bash
|
||
curl -X POST http://156.225.27.52:8000/rmbg/file \
|
||
-H "X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG" \
|
||
-F "file=@/path/to/your/image.jpg"
|
||
```
|
||
|
||
**请求示例 (Python)**:
|
||
```python
|
||
import requests
|
||
|
||
url = "http://156.225.27.52:8000/rmbg/file"
|
||
headers = {
|
||
"X-API-Key": "rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG"
|
||
}
|
||
files = {"file": open("image.jpg", "rb")}
|
||
response = requests.post(url, files=files, headers=headers)
|
||
|
||
# 保存结果
|
||
with open("result.png", "wb") as f:
|
||
f.write(response.content)
|
||
|
||
print(f"处理时间: {response.headers.get('X-Processing-Time')} 秒")
|
||
```
|
||
|
||
**请求示例 (JavaScript/Node.js)**:
|
||
```javascript
|
||
const FormData = require('form-data');
|
||
const fs = require('fs');
|
||
const axios = require('axios');
|
||
|
||
const form = new FormData();
|
||
form.append('file', fs.createReadStream('image.jpg'));
|
||
|
||
axios.post('http://156.225.27.52:8000/rmbg/file', form, {
|
||
headers: {
|
||
...form.getHeaders(),
|
||
'X-API-Key': 'rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG'
|
||
},
|
||
responseType: 'arraybuffer'
|
||
})
|
||
.then(response => {
|
||
fs.writeFileSync('result.png', response.data);
|
||
console.log('处理时间:', response.headers['x-processing-time'], '秒');
|
||
});
|
||
```
|
||
|
||
**响应**:
|
||
- **Content-Type**: `image/png`
|
||
- **Body**: PNG格式的图片二进制数据（背景已移除）
|
||
- **Headers**:
|
||
- `X-Processing-Time`: 处理时间（秒）
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"detail": "Invalid API key"
|
||
}
|
||
```
|
||
（当API密钥无效或缺失时）
|
||
|
||
或
|
||
```json
|
||
{
|
||
"detail": "只支持图片文件"
|
||
}
|
||
```
|
||
（当文件格式不支持时）
|
||
|
||
或
|
||
```json
|
||
{
|
||
"detail": "处理失败: [错误信息]"
|
||
}
|
||
```
|
||
（当处理失败时）
|
||
|
||
---
|
||
|
||
### 5. Base64 图片背景移除
|
||
|
||
**接口地址**: `POST /rmbg/base64`
|
||
|
||
**描述**: 通过Base64编码的图片数据移除背景（需要API密钥）
|
||
|
||
**Content-Type**: `application/json`
|
||
|
||
**请求头**:
|
||
```
|
||
X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"image_base64": "base64编码的图片字符串"
|
||
}
|
||
```
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| image_base64 | string | 是 | Base64编码的图片数据 |
|
||
|
||
**请求示例 (cURL)**:
|
||
```bash
|
||
curl -X POST http://156.225.27.52:8000/rmbg/base64 \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG" \
|
||
-d '{
|
||
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
|
||
}'
|
||
```
|
||
|
||
**请求示例 (Python)**:
|
||
```python
|
||
import requests
|
||
import base64
|
||
|
||
# 读取图片并转换为base64
|
||
with open("image.jpg", "rb") as f:
|
||
image_base64 = base64.b64encode(f.read()).decode('utf-8')
|
||
|
||
url = "http://156.225.27.52:8000/rmbg/base64"
|
||
headers = {
|
||
"Content-Type": "application/json",
|
||
"X-API-Key": "rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG"
|
||
}
|
||
data = {"image_base64": image_base64}
|
||
response = requests.post(url, json=data, headers=headers)
|
||
|
||
result = response.json()
|
||
if result["success"]:
|
||
# 保存结果
|
||
result_image = base64.b64decode(result["image_base64"])
|
||
with open("result.png", "wb") as f:
|
||
f.write(result_image)
|
||
print(f"处理时间: {result['processing_time']} 秒")
|
||
```
|
||
|
||
**请求示例 (JavaScript)**:
|
||
```javascript
|
||
const fs = require('fs');
|
||
const axios = require('axios');
|
||
|
||
// 读取图片并转换为base64
|
||
const imageBuffer = fs.readFileSync('image.jpg');
|
||
const imageBase64 = imageBuffer.toString('base64');
|
||
|
||
axios.post('http://156.225.27.52:8000/rmbg/base64', {
|
||
image_base64: imageBase64
|
||
}, {
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': 'rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG'
|
||
}
|
||
})
|
||
.then(response => {
|
||
if (response.data.success) {
|
||
const resultImage = Buffer.from(response.data.image_base64, 'base64');
|
||
fs.writeFileSync('result.png', resultImage);
|
||
console.log('处理时间:', response.data.processing_time, '秒');
|
||
}
|
||
});
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
|
||
"processing_time": 1.234
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| success | boolean | 是否成功 |
|
||
| image_base64 | string | Base64编码的结果图片（PNG格式） |
|
||
| processing_time | number | 处理时间（秒） |
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"detail": "Invalid API key"
|
||
}
|
||
```
|
||
（当API密钥无效或缺失时）
|
||
|
||
或
|
||
```json
|
||
{
|
||
"detail": "处理失败: [错误信息]"
|
||
}
|
||
```
|
||
（当处理失败时）
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| HTTP状态码 | 说明 |
|
||
|-----------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误（如文件格式不支持） |
|
||
| 401 | 未授权（API密钥无效或缺失） |
|
||
| 422 | 请求参数验证失败 |
|
||
| 500 | 服务器内部错误（如处理失败） |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **API密钥认证**:
|
||
- 所有核心接口（`/rmbg/file` 和 `/rmbg/base64`）都需要在请求头中添加 `X-API-Key`
|
||
- API密钥：`rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG`
|
||
- 健康检查和根端点无需密钥
|
||
2. **支持的图片格式**: 所有常见图片格式（JPG, PNG, JPEG等）
|
||
3. **输出格式**: 所有接口返回PNG格式的透明背景图片（RGBA模式）
|
||
4. **文件大小**: 建议图片大小不超过50MB
|
||
5. **处理时间**: 处理时间取决于图片大小和服务器负载，通常在0.5-5秒之间
|
||
6. **CORS**: 服务已配置CORS，支持跨域请求
|
||
|
||
---
|
||
|
||
## 完整使用示例
|
||
|
||
### Python完整示例
|
||
```python
|
||
import requests
|
||
import base64
|
||
from pathlib import Path
|
||
|
||
# 方法1: 文件上传
|
||
def remove_bg_file(image_path):
|
||
url = "http://156.225.27.52:8000/rmbg/file"
|
||
headers = {
|
||
"X-API-Key": "rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG"
|
||
}
|
||
with open(image_path, "rb") as f:
|
||
files = {"file": f}
|
||
response = requests.post(url, files=files, headers=headers)
|
||
|
||
if response.status_code == 200:
|
||
output_path = Path(image_path).stem + "_nobg.png"
|
||
with open(output_path, "wb") as f:
|
||
f.write(response.content)
|
||
print(f"✅ 成功! 结果已保存到: {output_path}")
|
||
return output_path
|
||
else:
|
||
print(f"❌ 失败: {response.json()}")
|
||
return None
|
||
|
||
# 方法2: Base64
|
||
def remove_bg_base64(image_path):
|
||
url = "http://156.225.27.52:8000/rmbg/base64"
|
||
headers = {
|
||
"Content-Type": "application/json",
|
||
"X-API-Key": "rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG"
|
||
}
|
||
|
||
with open(image_path, "rb") as f:
|
||
image_base64 = base64.b64encode(f.read()).decode('utf-8')
|
||
|
||
data = {"image_base64": image_base64}
|
||
response = requests.post(url, json=data, headers=headers)
|
||
|
||
if response.status_code == 200:
|
||
result = response.json()
|
||
if result["success"]:
|
||
output_path = Path(image_path).stem + "_nobg.png"
|
||
result_image = base64.b64decode(result["image_base64"])
|
||
with open(output_path, "wb") as f:
|
||
f.write(result_image)
|
||
print(f"✅ 成功! 处理时间: {result['processing_time']:.2f}秒")
|
||
return output_path
|
||
else:
|
||
print(f"❌ 失败: {response.json()}")
|
||
return None
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
image_path = "test_image.jpg"
|
||
|
||
# 使用文件上传方式
|
||
remove_bg_file(image_path)
|
||
|
||
# 或使用Base64方式
|
||
# remove_bg_base64(image_path)
|
||
```
|
||
|
||
### JavaScript/Node.js完整示例
|
||
```javascript
|
||
const axios = require('axios');
|
||
const FormData = require('form-data');
|
||
const fs = require('fs');
|
||
const path = require('path');
|
||
|
||
// 方法1: 文件上传
|
||
async function removeBgFile(imagePath) {
|
||
const form = new FormData();
|
||
form.append('file', fs.createReadStream(imagePath));
|
||
|
||
try {
|
||
const response = await axios.post(
|
||
'http://156.225.27.52:8000/rmbg/file',
|
||
form,
|
||
{
|
||
headers: {
|
||
...form.getHeaders(),
|
||
'X-API-Key': 'rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG'
|
||
},
|
||
responseType: 'arraybuffer'
|
||
}
|
||
);
|
||
|
||
const outputPath = path.parse(imagePath).name + '_nobg.png';
|
||
fs.writeFileSync(outputPath, response.data);
|
||
console.log(`✅ 成功! 结果已保存到: ${outputPath}`);
|
||
return outputPath;
|
||
} catch (error) {
|
||
console.error('❌ 失败:', error.response?.data || error.message);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
// 方法2: Base64
|
||
async function removeBgBase64(imagePath) {
|
||
const imageBuffer = fs.readFileSync(imagePath);
|
||
const imageBase64 = imageBuffer.toString('base64');
|
||
|
||
try {
|
||
const response = await axios.post(
|
||
'http://156.225.27.52:8000/rmbg/base64',
|
||
{ image_base64: imageBase64 },
|
||
{
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': 'rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG'
|
||
}
|
||
}
|
||
);
|
||
|
||
if (response.data.success) {
|
||
const outputPath = path.parse(imagePath).name + '_nobg.png';
|
||
const resultImage = Buffer.from(response.data.image_base64, 'base64');
|
||
fs.writeFileSync(outputPath, resultImage);
|
||
console.log(`✅ 成功! 处理时间: ${response.data.processing_time.toFixed(2)}秒`);
|
||
return outputPath;
|
||
}
|
||
} catch (error) {
|
||
console.error('❌ 失败:', error.response?.data || error.message);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
(async () => {
|
||
const imagePath = 'test_image.jpg';
|
||
|
||
// 使用文件上传方式
|
||
await removeBgFile(imagePath);
|
||
|
||
// 或使用Base64方式
|
||
// await removeBgBase64(imagePath);
|
||
})();
|
||
```
|
||
|
||
---
|
||
|
||
## 交互式API文档
|
||
|
||
访问 http://156.225.27.52:8000/docs 可以在浏览器中查看交互式API文档（Swagger UI），支持在线测试接口。
|
||
|
||
**注意**: 在Swagger UI中测试需要API密钥的接口时，需要先点击右上角的"Authorize"按钮（如果有），或者直接在请求头中添加 `X-API-Key`。
|
||
|
||
---
|
||
|
||
## API密钥
|
||
|
||
当前API密钥：
|
||
```
|
||
rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG
|
||
```
|
||
|
||
**请求头格式**:
|
||
```
|
||
X-API-Key: rmbg_sk_live_7K9mP2nQ5rT8vW1xY4zA6bC9dE0fG3hI6jK9mL2nO5pQ8rS1tU4vW7xY0zA3bC6dE9fG
|
||
```
|
||
|
||
**安全提示**:
|
||
- 请妥善保管API密钥，不要将其暴露在客户端代码中
|
||
- 建议通过环境变量或配置文件管理API密钥
|
||
- 定期更换API密钥以提高安全性
|
||
|