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界面生成（需要登录）

POST /user/v1/api-key/generate
Authorization: Bearer {JWT_TOKEN}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "keyValue": "ak_1234567890abcdef1234567890abcdef",
    "isActive": true,
    "createTime": "2025-10-20T10:00:00",
    "userRole": 0
  }
}

方式二：查看现有API Key

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）

POST /user/ai/tasks/submit
Authorization: Bearer ak_your_api_key_here
Content-Type: application/json

{
  "modelName": "sora_image",
  "prompt": "一只可爱的猫咪在花园里玩耍"
}

文生视频（Text to Video）

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

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编码

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..."
}

响应示例：

{
  "code": 200,
  "message": "任务提交成功",
  "data": {
    "taskNo": "TASK20251020143022ABC123",
    "status": "queued",
    "queuePosition": 3,
    "estimatedWaitTime": 90,
    "message": "任务创建成功，请通过任务编号查询进度"
  }
}

2. 查询任务详情

GET /user/ai/tasks/{taskNo}
Authorization: Bearer ak_your_api_key_here

响应示例：

{
  "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. 查询任务列表

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示例

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示例

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示例

# 提交任务
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