Xiaoxia AI
147 lines
3.3 KiB
Markdown
147 lines
3.3 KiB
Markdown
# API 文档
|
||
|
||
## 访问 API 文档
|
||
|
||
小虾 SaaS API 提供了两种交互式文档：
|
||
|
||
### 1. Swagger UI（推荐用于测试）
|
||
- **本地开发**: http://localhost:8000/docs
|
||
- **Staging**: http://47.98.113.167:8001/docs
|
||
- **Production**: http://47.98.113.167:8000/docs
|
||
|
||
**特点**：
|
||
- 交互式接口测试
|
||
- 可以直接在浏览器中发送请求
|
||
- 支持文件上传测试
|
||
|
||
### 2. ReDoc（推荐用于阅读）
|
||
- **本地开发**: http://localhost:8000/redoc
|
||
- **Staging**: http://47.98.113.167:8001/redoc
|
||
- **Production**: http://47.98.113.167:8000/redoc
|
||
|
||
**特点**：
|
||
- 更清晰的文档布局
|
||
- 更好的可读性
|
||
- 适合生成 PDF 或打印
|
||
|
||
### 3. OpenAPI JSON
|
||
- **本地开发**: http://localhost:8000/openapi.json
|
||
- **Staging**: http://47.98.113.167:8001/openapi.json
|
||
- **Production**: http://47.98.113.167:8000/openapi.json
|
||
|
||
**用途**：
|
||
- 生成客户端 SDK
|
||
- 导入到 Postman
|
||
- 集成到其他工具
|
||
|
||
---
|
||
|
||
## API 模块说明
|
||
|
||
### 🏥 健康检查
|
||
- `GET /api/v1/health` - 检查 API 服务状态
|
||
|
||
### 📁 项目管理
|
||
- `GET /api/v1/projects` - 列出所有项目
|
||
- `POST /api/v1/projects` - 创建新项目
|
||
- `GET /api/v1/projects/{id}` - 获取项目详情
|
||
|
||
### 📚 资产库管理
|
||
- `GET /api/v1/asset-libraries` - 列出资产库
|
||
- `POST /api/v1/asset-libraries` - 创建资产库
|
||
- `GET /api/v1/asset-libraries/{id}` - 获取资产库详情
|
||
|
||
### 🎬 素材资产
|
||
- `GET /api/v1/assets` - 列出素材资产
|
||
- `POST /api/v1/assets` - 创建素材资产（通常由系统自动创建）
|
||
- `GET /api/v1/assets/{id}` - 获取资产详情
|
||
|
||
### 📤 文件上传
|
||
- `POST /api/v1/upload` - 上传素材文件（视频、音频、图片等）
|
||
|
||
**上传示例**：
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/v1/upload" \
|
||
-H "Content-Type: multipart/form-data" \
|
||
-F "file=@/path/to/video.mp4" \
|
||
-F "workspace_id=ws_123" \
|
||
-F "project_id=proj_456" \
|
||
-F "library_id=lib_789"
|
||
```
|
||
|
||
### 🔄 导入任务
|
||
- `GET /api/v1/ingest-jobs` - 列出导入任务
|
||
- `GET /api/v1/ingest-jobs/{id}` - 获取任务详情
|
||
|
||
---
|
||
|
||
## 认证（待实现）
|
||
|
||
当前 API 暂未启用认证。生产环境将添加：
|
||
- JWT Token 认证
|
||
- API Key 认证
|
||
- OAuth 2.0
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
API 遵循标准 HTTP 状态码：
|
||
|
||
- `200 OK` - 请求成功
|
||
- `201 Created` - 资源创建成功
|
||
- `400 Bad Request` - 请求参数错误
|
||
- `404 Not Found` - 资源不存在
|
||
- `422 Unprocessable Entity` - 数据验证失败
|
||
- `500 Internal Server Error` - 服务器错误
|
||
|
||
错误响应格式：
|
||
```json
|
||
{
|
||
"detail": "错误描述"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用 Postman
|
||
|
||
1. 下载 OpenAPI JSON：http://localhost:8000/openapi.json
|
||
2. 在 Postman 中选择 **Import** → **File**
|
||
3. 选择下载的 `openapi.json` 文件
|
||
4. 所有接口将自动导入到 Postman
|
||
|
||
---
|
||
|
||
## 生成客户端 SDK
|
||
|
||
使用 OpenAPI Generator 生成各语言客户端：
|
||
|
||
```bash
|
||
# Python
|
||
openapi-generator-cli generate \
|
||
-i http://localhost:8000/openapi.json \
|
||
-g python \
|
||
-o ./client/python
|
||
|
||
# TypeScript
|
||
openapi-generator-cli generate \
|
||
-i http://localhost:8000/openapi.json \
|
||
-g typescript-axios \
|
||
-o ./client/typescript
|
||
|
||
# Java
|
||
openapi-generator-cli generate \
|
||
-i http://localhost:8000/openapi.json \
|
||
-g java \
|
||
-o ./client/java
|
||
```
|
||
|
||
---
|
||
|
||
## 反馈与支持
|
||
|
||
- **技术文档**: 参考项目 `docs/` 目录
|
||
- **问题反馈**: 提交 Issue 到代码仓库
|
||
- **联系方式**: dev@xiaoxiajianji.com
|