[Claude Workbench] Initial commit - preserving existing code
This commit is contained in:
Claude Workbench
353
AI_API_KEY_INTEGRATION_GUIDE.md
Normal file
353
AI_API_KEY_INTEGRATION_GUIDE.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# AI任务API集成指南
|
||||
|
||||
## 📋 概述
|
||||
|
||||
本系统现已支持通过**API Key**调用AI生成服务，无需JWT Token认证。所有用户（会员和非会员）都可以：
|
||||
|
||||
1. ✅ 生成个人专属的API Key
|
||||
2. ✅ 使用API Key + 积分调用AI服务
|
||||
3. ✅ 支持文生图、文生视频、图生视频三种模式
|
||||
|
||||
---
|
||||
|
||||
## 🔑 获取API Key
|
||||
|
||||
### 方式一：通过Web界面生成（需要登录）
|
||||
|
||||
```http
|
||||
POST /user/v1/api-key/generate
|
||||
Authorization: Bearer {JWT_TOKEN}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"keyValue": "ak_1234567890abcdef1234567890abcdef",
|
||||
"isActive": true,
|
||||
"createTime": "2025-10-20T10:00:00",
|
||||
"userRole": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方式二：查看现有API Key
|
||||
|
||||
```http
|
||||
GET /user/v1/api-key/info
|
||||
Authorization: Bearer {JWT_TOKEN}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 使用API Key调用AI服务
|
||||
|
||||
### 认证方式
|
||||
|
||||
所有AI任务接口都支持以下两种认证方式：
|
||||
|
||||
| 方式 | 适用场景 | Header格式 |
|
||||
|------|----------|-----------|
|
||||
| **JWT Token** | Web端用户 | `Authorization: Bearer {jwt_token}` |
|
||||
| **API Key** | 开发者/第三方集成 | `Authorization: Bearer {api_key}` |
|
||||
|
||||
> 💡 **提示**：系统会自动识别Token类型（JWT或API Key），无需额外配置。
|
||||
|
||||
---
|
||||
|
||||
## 📝 API接口说明
|
||||
|
||||
### 1. 提交AI任务
|
||||
|
||||
#### 文生图（Text to Image）
|
||||
|
||||
```http
|
||||
POST /user/ai/tasks/submit
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"modelName": "sora_image",
|
||||
"prompt": "一只可爱的猫咪在花园里玩耍"
|
||||
}
|
||||
```
|
||||
|
||||
#### 文生视频（Text to Video）
|
||||
|
||||
```http
|
||||
POST /user/ai/tasks/submit
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"modelName": "sora_video2",
|
||||
"prompt": "一只猫咪在夕阳下奔跑，镜头缓缓推进"
|
||||
}
|
||||
```
|
||||
|
||||
#### 图生视频（Image to Video）
|
||||
|
||||
**方式1：使用图片URL**
|
||||
```http
|
||||
POST /user/ai/tasks/submit
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"modelName": "sora_video2",
|
||||
"prompt": "让这个场景动起来，添加生动的细节",
|
||||
"imageUrl": "https://example.com/image.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
**方式2：使用Base64编码**
|
||||
```http
|
||||
POST /user/ai/tasks/submit
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"modelName": "sora_video2",
|
||||
"prompt": "让这个场景动起来，添加生动的细节",
|
||||
"imageBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "任务提交成功",
|
||||
"data": {
|
||||
"taskNo": "TASK20251020143022ABC123",
|
||||
"status": "queued",
|
||||
"queuePosition": 3,
|
||||
"estimatedWaitTime": 90,
|
||||
"message": "任务创建成功，请通过任务编号查询进度"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 查询任务详情
|
||||
|
||||
```http
|
||||
GET /user/ai/tasks/{taskNo}
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
```
|
||||
|
||||
**响应示例：**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"taskNo": "TASK20251020143022ABC123",
|
||||
"modelName": "sora_image",
|
||||
"status": "completed",
|
||||
"progress": 100,
|
||||
"promptSnippet": "一只可爱的猫咪在花园里玩耍",
|
||||
"resultUrl": "https://example.com/result.jpg",
|
||||
"createTime": "2025-10-20T14:30:22",
|
||||
"completeTime": "2025-10-20T14:31:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 查询任务列表
|
||||
|
||||
```http
|
||||
GET /user/ai/tasks/list?page=1&size=10&status=completed
|
||||
Authorization: Bearer ak_your_api_key_here
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💰 积分消费规则
|
||||
|
||||
| 模型名称 | 描述 | 积分消耗 | 对应价格 |
|
||||
|---------|------|---------|---------|
|
||||
| `sora_image` | Sora高质量图片生成 | 11积分 | ¥0.015 |
|
||||
| `gpt-4o-image` | GPT-4o图片生成 | 11积分 | ¥0.015 |
|
||||
| `sora_video2` | Sora视频生成（竖屏10秒） | 160积分 | ¥0.225 |
|
||||
| `sora_video2-landscape` | Sora视频生成（横屏10秒） | 160积分 | ¥0.225 |
|
||||
| `sora_video2-15s` | Sora视频生成（竖屏15秒） | 260积分 | ¥0.375 |
|
||||
| `sora_video2-landscape-15s` | Sora视频生成（横屏15秒） | 260积分 | ¥0.375 |
|
||||
| `sora-2-pro-all` | Sora Pro高清视频 | 420积分 | ¥0.60 |
|
||||
|
||||
> 💡 **说明**：1人民币 = 1000积分，系统在第三方API价格基础上加价50%
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 错误码说明
|
||||
|
||||
| 状态码 | 说明 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| `200` | 成功 | - |
|
||||
| `400` | 参数错误 | 检查请求参数是否正确 |
|
||||
| `401` | 未认证 | 检查API Key是否有效 |
|
||||
| `402` | 积分不足 | 充值积分后重试 |
|
||||
| `404` | 任务不存在 | 检查任务编号是否正确 |
|
||||
| `500` | 服务器错误 | 联系技术支持 |
|
||||
|
||||
---
|
||||
|
||||
## 🔒 安全建议
|
||||
|
||||
1. **保护API Key**：不要在客户端代码或公开仓库中硬编码API Key
|
||||
2. **使用环境变量**：将API Key存储在环境变量中
|
||||
3. **定期刷新**：定期刷新API Key以提高安全性
|
||||
4. **监控使用**：定期检查API Key的使用情况
|
||||
|
||||
---
|
||||
|
||||
## 💻 代码示例
|
||||
|
||||
### Python示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
API_KEY = "ak_your_api_key_here"
|
||||
BASE_URL = "https://your-domain.com"
|
||||
|
||||
def submit_task(model_name, prompt, image_url=None):
|
||||
"""提交AI任务"""
|
||||
headers = {
|
||||
"Authorization": f"Bearer {API_KEY}",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
|
||||
payload = {
|
||||
"modelName": model_name,
|
||||
"prompt": prompt
|
||||
}
|
||||
|
||||
if image_url:
|
||||
payload["imageUrl"] = image_url
|
||||
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/user/ai/tasks/submit",
|
||||
headers=headers,
|
||||
json=payload
|
||||
)
|
||||
|
||||
return response.json()
|
||||
|
||||
def get_task_status(task_no):
|
||||
"""查询任务状态"""
|
||||
headers = {
|
||||
"Authorization": f"Bearer {API_KEY}"
|
||||
}
|
||||
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/user/ai/tasks/{task_no}",
|
||||
headers=headers
|
||||
)
|
||||
|
||||
return response.json()
|
||||
|
||||
# 使用示例
|
||||
result = submit_task("sora_image", "一只可爱的猫咪")
|
||||
print(f"任务编号: {result['data']['taskNo']}")
|
||||
|
||||
status = get_task_status(result['data']['taskNo'])
|
||||
print(f"任务状态: {status['data']['status']}")
|
||||
```
|
||||
|
||||
### Node.js示例
|
||||
|
||||
```javascript
|
||||
const axios = require('axios');
|
||||
|
||||
const API_KEY = 'ak_your_api_key_here';
|
||||
const BASE_URL = 'https://your-domain.com';
|
||||
|
||||
async function submitTask(modelName, prompt, imageUrl = null) {
|
||||
const headers = {
|
||||
'Authorization': `Bearer ${API_KEY}`,
|
||||
'Content-Type': 'application/json'
|
||||
};
|
||||
|
||||
const payload = {
|
||||
modelName,
|
||||
prompt
|
||||
};
|
||||
|
||||
if (imageUrl) {
|
||||
payload.imageUrl = imageUrl;
|
||||
}
|
||||
|
||||
const response = await axios.post(
|
||||
`${BASE_URL}/user/ai/tasks/submit`,
|
||||
payload,
|
||||
{ headers }
|
||||
);
|
||||
|
||||
return response.data;
|
||||
}
|
||||
|
||||
async function getTaskStatus(taskNo) {
|
||||
const headers = {
|
||||
'Authorization': `Bearer ${API_KEY}`
|
||||
};
|
||||
|
||||
const response = await axios.get(
|
||||
`${BASE_URL}/user/ai/tasks/${taskNo}`,
|
||||
{ headers }
|
||||
);
|
||||
|
||||
return response.data;
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
(async () => {
|
||||
const result = await submitTask('sora_image', '一只可爱的猫咪');
|
||||
console.log(`任务编号: ${result.data.taskNo}`);
|
||||
|
||||
const status = await getTaskStatus(result.data.taskNo);
|
||||
console.log(`任务状态: ${status.data.status}`);
|
||||
})();
|
||||
```
|
||||
|
||||
### cURL示例
|
||||
|
||||
```bash
|
||||
# 提交任务
|
||||
curl -X POST "https://your-domain.com/user/ai/tasks/submit" \
|
||||
-H "Authorization: Bearer ak_your_api_key_here" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"modelName": "sora_image",
|
||||
"prompt": "一只可爱的猫咪在花园里玩耍"
|
||||
}'
|
||||
|
||||
# 查询任务状态
|
||||
curl -X GET "https://your-domain.com/user/ai/tasks/TASK20251020143022ABC123" \
|
||||
-H "Authorization: Bearer ak_your_api_key_here"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
1. **轮询查询**：任务提交后，建议每5-10秒轮询一次任务状态
|
||||
2. **超时处理**：设置合理的超时时间（建议5-10分钟）
|
||||
3. **错误重试**：遇到网络错误时实现指数退避重试
|
||||
4. **并发控制**：单用户最多同时运行3个任务
|
||||
5. **结果缓存**：completed状态的任务结果可以缓存，避免重复查询
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如有问题，请联系：
|
||||
- 📧 Email: support@1818ai.com
|
||||
- 💬 技术文档: https://docs.1818ai.com
|
||||
- 🐛 问题反馈: https://github.com/1818ai/issues
|
||||
|
||||
---
|
||||
|
||||
**最后更新时间：2025-10-20**
|
||||
|
||||
Reference in New Issue
Block a user