介绍

这是一个基于FastAPI构建的后端API，集成了多种外部服务，包括OpenAI、飞书、PDF处理工具、阿里云发票识别、Coze和Frameio等。API设计为模块化结构，每个模块可以独立工作，也可以组合成自动化工作流。

本文档提供了API的详细使用说明，包括每个端点的请求参数、响应格式和示例代码。

认证

所有API请求都需要通过API密钥进行认证。您可以在请求头中添加X-API-KEY字段来提供您的API密钥。

curl -X GET "https://api.example.com/openai/models" \
     -H "X-API-KEY: your-api-key-here"

如果未提供API密钥或API密钥无效，API将返回401 Unauthorized错误。

错误处理

API使用标准的HTTP状态码来表示请求的结果。一般来说，2xx状态码表示成功，4xx状态码表示客户端错误，5xx状态码表示服务器错误。

错误响应的格式如下：

{
    "code": 400,
    "detail": "400 - Bad Request - Invalid or malformed request."
}

常见的错误码包括：

  • 400 Bad Request：请求参数无效或格式错误
  • 401 Unauthorized：未提供API密钥或API密钥无效
  • 403 Forbidden：没有权限访问请求的资源
  • 404 Not Found：请求的资源不存在
  • 429 Too Many Requests：请求频率超过限制
  • 500 Internal Server Error：服务器内部错误

OpenAI API

POST /openai/chat

创建一个新的对话，支持文本和图像输入。

请求参数

model string 必填
要使用的模型ID，例如 "gpt-4o"。
messages array 必填
对话消息数组，每个消息包含 role（角色）和 content（内容）字段。
temperature number
采样温度，控制输出的随机性。值越高，输出越随机。默认为0.7。

响应

{
    "id": "chatcmpl-123456789",
    "object": "chat.completion",
    "created": 1677858242,
    "model": "gpt-4o",
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "这是助手的回复内容。"
            },
            "finish_reason": "stop",
            "index": 0
        }
    ],
    "usage": {
        "prompt_tokens": 13,
        "completion_tokens": 7,
        "total_tokens": 20
    }
}

示例

cURL
Python
curl -X POST "https://api.example.com/openai/chat" \
     -H "X-API-KEY: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
         "model": "gpt-4o",
         "messages": [
             {
                 "role": "system",
                 "content": "你是一个有用的助手。"
             },
             {
                 "role": "user",
                 "content": "你好，请介绍一下自己。"
             }
         ],
         "temperature": 0.7
     }'
import requests
import json

url = "https://api.example.com/openai/chat"
headers = {
    "X-API-KEY": "your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "你是一个有用的助手。"
        },
        {
            "role": "user",
            "content": "你好，请介绍一下自己。"
        }
    ],
    "temperature": 0.7
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
GET /openai/models

获取可用的模型列表。

响应

{
    "data": [
        {
            "id": "gpt-4o",
            "object": "model",
            "created": 1677610602,
            "owned_by": "openai"
        },
        {
            "id": "gpt-4-turbo",
            "object": "model",
            "created": 1677649963,
            "owned_by": "openai"
        },
        {
            "id": "gpt-3.5-turbo",
            "object": "model",
            "created": 1677610602,
            "owned_by": "openai"
        }
    ],
    "object": "list"
}

示例

cURL
Python
curl -X GET "https://api.example.com/openai/models" \
     -H "X-API-KEY: your-api-key-here"
import requests

url = "https://api.example.com/openai/models"
headers = {
    "X-API-KEY": "your-api-key-here"
}

response = requests.get(url, headers=headers)
print(response.json())

飞书 API

POST /feishu/auth

获取飞书访问令牌（tenant_access_token）。

响应

{
    "code": 0,
    "msg": "ok",
    "tenant_access_token": "t-g1xxx...",
    "expire": 7200
}

示例

cURL
Python
curl -X POST "https://api.example.com/feishu/auth" \
     -H "X-API-KEY: your-api-key-here"
import requests

url = "https://api.example.com/feishu/auth"
headers = {
    "X-API-KEY": "your-api-key-here"
}

response = requests.post(url, headers=headers)
print(response.json())