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