Skip to content

API.md

Latest commit

 

History

History
296 lines (242 loc) · 8.99 KB

API.md

File metadata and controls

296 lines (242 loc) · 8.99 KB

Aurora 接口文档

本文档整理 Aurora 当前支持的接口、鉴权方式和 curl 示例。默认服务地址示例为 http://你的服务器ip:8080。

鉴权

受保护的 /v1/* 和 /backend-api/conversation 接口需要请求头：

Authorization: Bearer <AccessToken 或 RefreshToken>

鉴权值可以是：

  • 在环境变量 Authorization 中配置的服务访问 key。
  • ChatGPT access_token，通常以 eyJhbGciOiJSUzI1NiI 开头。
  • UUID 形式的免费 device id，仅适合普通聊天，不支持文件、图片、TTS 等需要登录账号的能力。

文件上传、文件问答、图片生成和 TTS 需要真实 ChatGPT access_token。你可以把多个 access token 一行一个放在项目根目录 access_tokens.txt，服务会轮询使用；也可以在请求头中直接传入临时 access token。

Token 接口

如果有team账号，可以传入 ChatGPT-Account-ID，使用 Team 工作区：

Authorization 传入 ChatGPT-Account-ID值

Authorization: Bearer <AccessToken 或 RefreshToken>, 如果没有传入ChatGPT-Account-ID就不使用team

refresh_token 换 access_token

curl --location 'http://你的服务器ip:8080/auth/refresh' \
--header 'Content-Type: application/json' \
--data '{
  "refresh_token": "你的 refresh_token"
}'

session_token 换 access_token

curl --location 'http://你的服务器ip:8080/auth/session' \
--header 'Content-Type: application/json' \
--data '{
  "session_token": "你的 __Secure-next-auth.session-token"
}'

返回中包含 access_token，/auth/session 还会返回可用的 session_token。

Chat Completions

curl --location 'http://你的服务器ip:8080/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "Say this is a test!"}
  ],
  "stream": true
}'

工具调用 (Tool Calling)

ChatGPT Web 不原生支持 OpenAI 的 function calling。Aurora 通过文本协议 <tool_call>{...}</tool_call> 模拟该能力：请求里声明 tools 字段时，Aurora 自动在 system prompt 中注入调用约定，解析模型输出中的 <tool_call> 块并转换为标准 OpenAI 格式的 tool_calls。

声明工具并发起调用

curl --location 'http://你的服务器ip:8080/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "列出当前目录的文件"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "bash",
      "description": "执行 shell 命令并返回输出",
      "parameters": {
        "type": "object",
        "properties": {
          "command": {"type": "string", "description": "要执行的命令"}
        },
        "required": ["command"]
      }
    }
  }]
}'

当模型决定调用工具时,Aurora 返回的响应 finish_reason 为 tool_calls,并在 choices[0].message.tool_calls 中列出调用：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "index": 0,
        "id": "call_a1b2c3d4",
        "type": "function",
        "function": {
          "name": "bash",
          "arguments": "{\"command\":\"ls -la\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {"prompt_tokens": 123, "completion_tokens": 18, "total_tokens": 141}
}

把工具执行结果回传给模型

由客户端(本服务不执行工具)执行 bash 命令,得到结果,再发起新一轮请求,把结果以 role: tool 消息回传:

curl --location 'http://你的服务器ip:8080/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "auto",
  "messages": [
    {"role": "user", "content": "列出当前目录的文件"},
    {"role": "assistant", "content": null, "tool_calls": [{
      "id": "call_a1b2c3d4",
      "type": "function",
      "function": {"name": "bash", "arguments": "{\"command\":\"ls -la\"}"}
    }]},
    {"role": "tool", "tool_call_id": "call_a1b2c3d4", "name": "bash", "content": "README.md\nmain.go\n"}
  ],
  "tools": [{
    "type": "function",
    "function": {
      "name": "bash",
      "description": "执行 shell 命令并返回输出",
      "parameters": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}
    }
  }]
}'

模型在收到工具结果后会给出最终文字答案,finish_reason 为 stop。

tool_choice

通过 tool_choice 字段控制工具调用行为,接受以下值:

  • "auto"(默认):模型自行决定是否调用
  • "none":禁止调用工具
  • "any":强制至少调用一个工具
  • {"type":"function","function":{"name":"bash"}}:强制调用指定工具
{
  "tool_choice": {"type": "function", "function": {"name": "bash"}},
  "tools": [...]
}

环境变量

变量 默认值 说明
TOOL_CALLING_ENABLED true 设为 false 时忽略请求中的 tools 字段,关闭模拟
REFUSAL_RETRIES 3 模型陷入"sandbox 隔离"拒绝循环时的最大重试次数
DEBUG_TOOL_LOG (空) 设为文件路径,记录每次工具解析的输入文本与解析结果(调试用)

限制

  • 强制非流式:工具调用模式会强制 stream=false(需要完整响应才能识别 sandbox 拒绝并重试)。客户端即使传 stream: true 也只会拿到单次 ChatCompletion。
  • 不在服务端执行工具:Aurora 只做协议转换,工具的实际执行完全由客户端负责。
  • 仅解析首个拒绝:当前实现不会处理"工具执行失败 → 重试"循环;若需重试,由客户端再次发起完整对话。

Responses API

curl --location 'http://你的服务器ip:8080/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "auto",
  "instructions": "用简洁中文回答。",
  "input": "总结一下 Aurora 支持哪些接口。",
  "stream": false
}'

模型列表

curl --location 'http://你的服务器ip:8080/v1/models' \
--header 'Authorization: Bearer access_token'

文件上传和文件问答

上传文件：

curl --location 'http://你的服务器ip:8080/v1/files' \
--header 'Authorization: Bearer access_token' \
--form 'purpose="assistants"' \
--form 'file=@"/path/to/test.pdf"'

使用返回的 id 或 file_id 继续问答：

curl --location 'http://你的服务器ip:8080/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "auto",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "input_file", "file_id": "file-xxx"},
      {"type": "text", "text": "总结这个文件"}
    ]
  }],
  "stream": false
}'

图片生成

curl --location 'http://你的服务器ip:8080/v1/images/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "gpt-image-2",
  "prompt": "A cute orange cat wearing sunglasses, digital art",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url"
}'

如需返回 base64，将 response_format 改为 b64_json。如果不传 response_format，默认返回 b64_json。

TTS 语音合成

curl --location 'http://你的服务器ip:8080/v1/audio/speech' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "model": "tts-1",
  "input": "Hello, this is a test!",
  "voice": "alloy",
  "response_format": "mp3"
}' \
--output speech.mp3

支持的 voice 映射包括 alloy、ash、coral、echo、fable、onyx、nova、sage、shimmer。支持的 response_format 包括 mp3、opus、aac、flac、wav、pcm，其中部分格式会由上游以 AAC 形式返回。

原始 ChatGPT Conversation 透传

curl --location 'http://你的服务器ip:8080/backend-api/conversation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer access_token' \
--data '{
  "action": "next",
  "model": "auto",
  "messages": [{
    "id": "00000000-0000-0000-0000-000000000001",
    "author": {"role": "user"},
    "content": {"content_type": "text", "parts": ["hello"]}
  }],
  "parent_message_id": "00000000-0000-0000-0000-000000000000",
  "timezone_offset_min": -480,
  "history_and_training_disabled": true
}'

注意事项

  • 插件模型和 gpt-4-plugins 已移除，不再支持 ChatGPT Plugins。
  • 图片、TTS、文件能力依赖登录态 access token，免费 UUID 账号不可用。
  • STREAM_MODE=false 时会强制关闭 Chat Completions 流式返回。
  • 本项目是 ChatGPT Web 能力转换服务，接口形状尽量兼容 OpenAI API，但并非 OpenAI 官方服务。