1818web-hoduan/AI_API_KEY_INTEGRATION_GUIDE.md

# 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**