API 接口文档

使用 RESTful API 实现应用与后台 AI 服务的交互

简介

AI逢源 API 提供了一套完整的 RESTful 接口,让您能够在自己的应用程序中轻松集成 AI 能力。通过 API,您可以创建图像生成任务、查询任务状态、获取生成结果等。

在开始之前,请确保您已经在API密钥管理页面创建了 API 密钥。

认证方式

所有 API 请求都需要在请求头中携带有效的 API 密钥进行认证，支持两种方式：

HTTP Header (方式一) 
X-API-Key: YOUR_API_KEY
HTTP Header (方式二) 
Authorization: Bearer YOUR_API_KEY

示例请求

cURL 
curl -X GET "/api/user/info" \
  -H "X-API-Key: sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

基础地址

所有 API 请求的基础地址为：

Base URL 
https://your-domain.com

错误处理

API 使用标准 HTTP 状态码表示请求结果。

状态码 说明
200 请求成功
400 请求参数错误
401 未授权,API密钥无效或过期
403 禁止访问,积分不足或权限不足
404 资源不存在
429 请求过于频繁
500 服务器内部错误

错误响应格式

JSON 
{
  "success": false,
  "message": "错误信息",
  "code": "ERROR_CODE"
}

用户信息

GET /api/user/info

获取当前用户信息,包括账户积分和会员状态

响应示例

JSON 
{
  "success": true,
  "data": {
    "id": 1,
    "username": "user123",
    "credits": 1000,
    "vip_level": 1,
    "vip_expire_at": "2025-12-31"
  }
}

服务列表

GET /api/service/list

获取当前可用的 AI 服务列表（无需认证）

响应示例

JSON 
{
  "success": true,
  "data": {
    "services": [
      {
        "id": 1,
        "service_code": "image_generation",
        "name": "通用图像生成",
        "category": "image",
        "description": "基于 AI 的图像生成服务",
        "cost_per_request": 20.00,
        "vip_discount": 0.8,
        "model_endpoint": "/api/v1/jobs/createTask"
      }
    ]
  }
}

当前可用服务

加载中...

调用AI服务

POST /api/service/invoke

调用 AI 服务，需要 API Key 认证

请求参数

参数名 类型 说明
service_code 必填 string 服务代码，如 "image_generation"（从服务列表获取）
params 必填 object 服务参数对象，包含 prompt、product_image 等

params 对象内常用字段

参数名 类型 说明
prompt string 提示词，描述想要生成的内容
product_image string 产品图片 URL（某些服务需要）

请求示例

cURL 
curl -X POST "/api/service/invoke" \
  -H "X-API-Key: sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "service_code": "image_generation",
    "params": {
      "prompt": "一只可爱的猫咪在阳光下"
    }
  }'

响应示例

JSON 
{
  "success": true,
  "data": {
    "id": "task_abc123",
    "status": "pending",
    "created_at": "2025-01-20T10:00:00Z"
  }
}

查询任务状态

GET /api/service/task/{task_id}

获取任务详情，需要 API Key 认证。工作中的任务会实时查询最新状态。

任务状态说明

状态 说明
pending 等待处理
processing 正在处理
completed 处理完成
failed 处理失败

任务列表

GET /api/task/list

获取当前用户的任务列表，支持分页和状态筛选（需要 API Key 认证）

查询参数

参数 参数 说明
page integer 页码,默认为1
limit integer 每页数量,默认为20,最大为100
status string 按状态筛选

速率限制

为了保证服务稳定,API 设有以下速率限制：

  • 普通用户:每分钟 60 次请求
  • VIP用户:每分钟 300 次请求

请求过于频繁,接口返回 429 状态码。请稍后再试

Webhooks

当任务状态发生变化时,Webhook 会主动通知,避免频繁轮询接口查询任务状态。

Webhook 具体内容详见文档,当前版本暂不支持。