xiaoxia-saas/docs/API.md

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 - 上传素材文件（视频、音频、图片等）

上传示例：

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 - 服务器错误

错误响应格式：

{
  "detail": "错误描述"
}

---

使用 Postman

1. 下载 OpenAPI JSON：http://localhost:8000/openapi.json
2. 在 Postman 中选择 Import → File
3. 选择下载的 openapi.json 文件
4. 所有接口将自动导入到 Postman

---

生成客户端 SDK

使用 OpenAPI Generator 生成各语言客户端：

# 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