354 lines
8.0 KiB
Markdown
354 lines
8.0 KiB
Markdown
# 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**
|
||
|