openapi: 3.0.3
info:
  title: Liya AI — OpenAI 兼容 API
  description: |
    适用于 Liya AI 平台的 OpenAI 兼容 REST API。

    使用此 API 可将 Liya AI 助手集成到原生支持 OpenAI Chat Completions API 的应用程序中（例如 AnythingLLM、OpenClaw、LangChain 等）。

    ## 身份验证 (Authentication)
    请在 `Authorization` 头部包含您的 Liya AI API 密钥：

    ```
    Authorization: Bearer *****
    ```

    ## 基础 URL (Base URL)
    请使用为您项目分配的后端实例地址：

    ```
    https://app-{X}-ai.liyalabs.com/api/v1/openai/v1
    ```

    > ℹ️ `/v1` 后缀是**必需的** — AnythingLLM、OpenAI SDK、LangChain 等
    > 客户端会在基础 URL 后追加 `/chat/completions` 和 `/models`，这是
    > OpenAI 的标准约定（LM Studio、vLLM、llama.cpp 均遵循）。
    >
    > 不带 `/v1` 的旧路径（`/api/v1/openai/chat/completions` 和
    > `/api/v1/openai/models`）仍然可用，但已弃用。

    ## 支持的端点
    | 方法 | 路径 | 说明 |
    |------|------|------|
    | POST | `/api/v1/openai/v1/chat/completions` | 聊天补全（OpenAI 格式） |
    | GET  | `/api/v1/openai/v1/models`           | 将助手列为 OpenAI 模型 |
    | GET  | `/api/v1/openai`                     | 连通性探测（无需鉴权） |

    ## 兼容性
    此端点实现了标准的 OpenAI `ChatCompletion` 对象结构。
    令牌使用量将根据您的账户定价层级进行跟踪。

  version: 0.1.0
  contact:
    name: Liya Labs 支持
    url: https://liyalabs.com
    email: support@liyalabs.com

servers:
  - url: https://app-{X}-ai.liyalabs.com
    description: 将 {X} 替换为您的项目实例 ID。
    variables:
      X:
        default: "1"
        description: 项目实例编号

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /api/v1/openai/v1/chat/completions:
    post:
      summary: 创建聊天补全
      operationId: createChatCompletion
      description: |
        以 OpenAI `ChatCompletion` 格式返回 AI 响应。

        **旧路径：** `POST /api/v1/openai/chat/completions`（不带 `/v1`）
        仍受支持以兼容已部署的集成，但已弃用。
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  description: 您的 Liya AI 助手 ID。
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum: [system, user, assistant]
                      content:
                        type: string
      responses:
        '200':
          description: 成功响应
        '402':
          description: 余额不足
