{
  "openapi": "3.1.0",
  "info": {
    "title": "PingToken AI API（对外中继面）",
    "summary": "PingToken 统一 AI API 网关对外中继接口：OpenAI / Anthropic / Gemini / SystemOne 四协议线，覆盖文本对话、图像生成、视频生成、音频、向量、重排序、决策与余额查询。",
    "description": "PingToken 对外中继 API 契约（单一真源）。覆盖范围 = 代码实际注册且可用的公开 AI 端点（router/relay-router.go、router/video-router.go、router/dashboard.go）；后台管理 API（/api/* 门户专用）与 501 未实现桩不在本契约内。\n\n鉴权：令牌密钥（Token Key）三种形态等价——OpenAI 惯例 `Authorization: Bearer sk-…`、Anthropic 惯例 `x-api-key: sk-…`、Gemini 惯例 `x-goog-api-key` 头或 `?key=` 查询参数。\n\nBase URL：OpenAI 协议线填 `{baseUrl}/v1`；Anthropic 协议线填根地址 `{baseUrl}`（SDK 自动拼接 /v1/messages）；Gemini 协议线填根地址 `{baseUrl}`。\n\n错误契约（买家 7 码）：400 invalid_request / 401 token_invalid / 404 invalid_request / 429 client_rate_limited / 503 service_unavailable。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://pingtoken.cc",
      "description": "商用生产环境"
    }
  ],
  "tags": [
    {
      "name": "模型查询",
      "description": "模型列表与单模型查询（OpenAI/Anthropic/Gemini 三协议自适应）"
    },
    {
      "name": "文本对话",
      "description": "Chat / Completions / Claude Messages / Responses / Realtime"
    },
    {
      "name": "图像生成",
      "description": "OpenAI 兼容图像生成与编辑（平台转存，链接保留 7 天）"
    },
    {
      "name": "视频生成",
      "description": "异步任务线（OpenAI videos / video.generations / Kling / Jimeng）"
    },
    {
      "name": "音频",
      "description": "语音合成与转写"
    },
    {
      "name": "向量与重排序",
      "description": "Embeddings 与 Rerank"
    },
    {
      "name": "SystemOne 决策",
      "description": "POST /v1/systemone 决策协议线（与 TypeSafe 直连同形）"
    },
    {
      "name": "余额与用量",
      "description": "余额查询与 OpenAI legacy billing 端点"
    },
    {
      "name": "错误契约",
      "description": "平台统一错误面（买家 7 码）"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    },
    {
      "geminiApiKey": []
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "tags": [
          "模型查询"
        ],
        "summary": "模型列表（三协议自适应）",
        "description": "携带 `anthropic-version` 请求头 → Anthropic 格式；携带 `x-goog-api-key` 头或 `?key=` 参数 → Gemini 格式；否则 OpenAI 格式。可见性 = 可服务的已发布聚合模型 ∪ 本人自用调用名 ∪ 本人用户级聚合名；AUTO 开启时含 `auto` 虚拟名。",
        "operationId": "listModels",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          },
          {
            "geminiApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "anthropic-version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "出现即按 Anthropic 标准格式应答（如 2023-06-01）"
          },
          {
            "name": "key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Gemini 形态触发（亦可经 x-goog-api-key 头）"
          }
        ],
        "responses": {
          "200": {
            "description": "OpenAI 格式列表（缺省）；Anthropic/Gemini 形态见各协议标准",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIModelList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "429": {
            "$ref": "#/components/responses/ClientRateLimited"
          }
        }
      }
    },
    "/v1/models/{model_path}": {
      "get": {
        "tags": [
          "模型查询"
        ],
        "summary": "单模型查询",
        "description": "模型名支持 `vendor/model` 斜杠形态（单段参数不吞斜杠）。不带 `anthropic-version` 头按 OpenAI 格式；带头按 Anthropic 格式。不可服务/不存在的聚合按 404 处理。",
        "operationId": "retrieveModel",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "model_path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "模型名，可含斜杠"
          },
          {
            "name": "anthropic-version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "模型存在且可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIModel"
                }
              }
            }
          },
          "403": {
            "description": "令牌模型白名单拦截（403 + OpenAI error 体）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          }
        }
      },
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "Gemini 中继（/v1/models/{model}:{action} 形态）",
        "description": "Gemini 协议入站的 /v1/models 路径中继分支，经 Distribute 解析模型名后按 Gemini 信封转发。",
        "operationId": "relayModelsPath",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "model_path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "models/{model}:{action} 形态路径"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gemini 协议应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1beta/models": {
      "get": {
        "tags": [
          "模型查询"
        ],
        "summary": "模型列表（Gemini 格式）",
        "operationId": "listModelsGemini",
        "security": [
          {
            "geminiApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Gemini models.list 应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1beta/models/{path}": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "Gemini generateContent 中继",
        "description": "Gemini API 原生路径 `/v1beta/models/{model}:{action}`（generateContent / streamGenerateContent 等），按 Gemini 信封转发。",
        "operationId": "relayGeminiGenerate",
        "security": [
          {
            "geminiApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "{model}:{action} 形态路径"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gemini 协议应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1beta/openai/models": {
      "get": {
        "tags": [
          "模型查询"
        ],
        "summary": "模型列表（v1beta 下 OpenAI 格式）",
        "operationId": "listModelsV1betaOpenAI",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "OpenAI 格式列表",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIModelList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "对话补全（OpenAI 兼容）",
        "operationId": "createChatCompletion",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "补全应答（stream=true 时为 SSE 流）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ClientRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/completions": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "文本补全（OpenAI 兼容 legacy）",
        "operationId": "createCompletion",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  },
                  "max_tokens": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "补全应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "Claude Messages（Anthropic 原生）",
        "description": "Anthropic Messages API 形态；Base URL 填根地址（SDK 自动拼接 /v1/messages）。请求须带 `anthropic-version` 头；鉴权 `x-api-key` 与 Bearer 均可。`max_tokens` 必填。",
        "operationId": "createClaudeMessage",
        "security": [
          {
            "apiKeyHeader": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "anthropic-version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "messages",
                  "max_tokens"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ChatMessage"
                    }
                  },
                  "max_tokens": {
                    "type": "integer",
                    "description": "必填（Anthropic 标准）"
                  },
                  "system": {
                    "type": "string"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  },
                  "temperature": {
                    "type": "number"
                  },
                  "thinking": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "扩展思考配置"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Messages 应答（stream=true 时为 SSE 流）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ClientRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "OpenAI Responses",
        "operationId": "createResponse",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {
                    "description": "文本或结构化输入"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  },
                  "instructions": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Responses 应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/responses/compact": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "OpenAI Responses（压缩形态）",
        "operationId": "createResponseCompact",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Responses 应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/alpha/search": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "Codex 独立联网搜索（Alpha）",
        "operationId": "createAlphaSearch",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "搜索应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/realtime": {
      "get": {
        "tags": [
          "文本对话"
        ],
        "summary": "Realtime WebSocket",
        "description": "OpenAI Realtime WebSocket 升级端点。",
        "operationId": "realtimeSocket",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "101": {
            "description": "WebSocket 协议升级"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1/systemone": {
      "post": {
        "tags": [
          "SystemOne 决策"
        ],
        "summary": "SystemOne 决策协议",
        "description": "决策线专用端点（不可经 /v1/chat/completions 调用，否则 400）。与 TypeSafe 直连 wire 同形（drop-in）。计费与 chat 完全同构（按 usage token 计费）。约束：questions 必填且 ≤32 题；整体 body ≤64KiB；题型 ∈ noul / boolean / choice / score。",
        "operationId": "createSystemOneDecision",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SystemOneRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "决策应答（answers 按题型返回 noul/choice/score 结构）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemOneResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "429": {
            "$ref": "#/components/responses/ClientRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "tags": [
          "图像生成"
        ],
        "summary": "图像生成",
        "description": "按次计费（单价 × 张数系数 × 尺寸系数）。size 支持 2^n 比例（512x512 / 1024x1024 / 1024x1536 / 1024x1792 / 4096x4096），16:9 等非 2^n 比例静默降级 1024x1024。返回平台转存链接（/api/image/...），保留 7 天。水印三态：official / PingToken / 自定义（平台启用自定义时 watermark_text 必填 ≤64 字符）。",
        "operationId": "createImageGeneration",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "生成应答（url 或 b64_json）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "429": {
            "$ref": "#/components/responses/ClientRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "tags": [
          "图像生成"
        ],
        "summary": "图像编辑",
        "description": "须携带 1~5 张参考图，单张 ≤10MB。",
        "operationId": "createImageEdit",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageGenerationRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "prompt",
                  "image"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "image": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "minItems": 1,
                    "maxItems": 5,
                    "description": "1~5 张参考图，单张 ≤10MB"
                  },
                  "n": {
                    "type": "integer"
                  },
                  "size": {
                    "type": "string"
                  },
                  "response_format": {
                    "type": "string",
                    "enum": [
                      "url",
                      "b64_json"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "编辑应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/edits": {
      "post": {
        "tags": [
          "图像生成"
        ],
        "summary": "图像编辑（别名，与 /v1/images/edits 等价）",
        "operationId": "createImageEditAlias",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "编辑应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "tags": [
          "向量与重排序"
        ],
        "summary": "向量嵌入",
        "operationId": "createEmbedding",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "嵌入应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/engines/{model}/embeddings": {
      "post": {
        "tags": [
          "向量与重排序"
        ],
        "summary": "向量嵌入（legacy engines 形态）",
        "operationId": "createEmbeddingLegacy",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "model",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "嵌入应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/rerank": {
      "post": {
        "tags": [
          "向量与重排序"
        ],
        "summary": "重排序",
        "operationId": "createRerank",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "query",
                  "documents"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "query": {
                    "type": "string"
                  },
                  "documents": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "top_n": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "重排序应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/audio/speech": {
      "post": {
        "tags": [
          "音频"
        ],
        "summary": "语音合成（TTS）",
        "operationId": "createSpeech",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "input",
                  "voice"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {
                    "type": "string"
                  },
                  "voice": {
                    "type": "string"
                  },
                  "response_format": {
                    "type": "string"
                  },
                  "speed": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "音频二进制流",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/audio/transcriptions": {
      "post": {
        "tags": [
          "音频"
        ],
        "summary": "语音转写",
        "operationId": "createTranscription",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "file"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "language": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "response_format": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "转写应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/audio/translations": {
      "post": {
        "tags": [
          "音频"
        ],
        "summary": "语音翻译",
        "operationId": "createTranslation",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "model",
                  "file"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "response_format": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "翻译应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/moderations": {
      "post": {
        "tags": [
          "文本对话"
        ],
        "summary": "内容审核",
        "operationId": "createModeration",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "审核应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/video/generations": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频生成（异步任务创建）",
        "operationId": "createVideoGeneration",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "model"
                ],
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "duration": {
                    "type": "number",
                    "description": "时长（秒），上游计费系数"
                  },
                  "seconds": {
                    "type": "number"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务创建应答（task_id）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/video/generations/{task_id}": {
      "get": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频任务查询",
        "operationId": "getVideoGenerationTask",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态与结果",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          }
        }
      }
    },
    "/v1/videos": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频创建（OpenAI videos 兼容）",
        "operationId": "createVideo",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务创建应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/videos/{task_id}": {
      "get": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频任务查询（OpenAI videos 兼容）",
        "operationId": "getVideoTask",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态与结果",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          }
        }
      }
    },
    "/v1/videos/{task_id}/content": {
      "get": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频内容下载",
        "description": "接受令牌鉴权（Token Key）或会话鉴权（dashboard）。",
        "operationId": "getVideoContent",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "视频二进制流",
            "content": {
              "video/mp4": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "404": {
            "$ref": "#/components/responses/ModelNotFound"
          }
        }
      }
    },
    "/v1/videos/{video_id}/remix": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "视频再创作（remix）",
        "operationId": "remixVideo",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "video_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务创建应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/kling/v1/videos/text2video": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "Kling 文生视频",
        "operationId": "klingText2Video",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务创建应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/kling/v1/videos/image2video": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "Kling 图生视频",
        "operationId": "klingImage2Video",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务创建应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/kling/v1/videos/text2video/{task_id}": {
      "get": {
        "tags": [
          "视频生成"
        ],
        "summary": "Kling 文生视频任务查询",
        "operationId": "klingText2VideoFetch",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态与结果",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/kling/v1/videos/image2video/{task_id}": {
      "get": {
        "tags": [
          "视频生成"
        ],
        "summary": "Kling 图生视频任务查询",
        "operationId": "klingImage2VideoFetch",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务状态与结果",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/jimeng/": {
      "post": {
        "tags": [
          "视频生成"
        ],
        "summary": "即梦官方 API 直通（火山引擎 Action 形态）",
        "description": "映射到官方 `?Action=CVSync2AsyncSubmitTask&Version=2022-08-31` 与 `?Action=CVSync2AsyncGetResult&Version=2022-08-31`。",
        "operationId": "jimengAction",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "官方协议应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "令牌余额查询",
        "operationId": "getTokenBalance",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "余额应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1beta/balance": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "令牌余额查询（Gemini 形态）",
        "operationId": "getTokenBalanceGemini",
        "security": [
          {
            "geminiApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "余额应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1/dashboard/billing/subscription": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "OpenAI legacy billing 配额查询",
        "description": "`hard_limit_usd − total_usage_usd` 一步得剩余余额（cc-switch Usage Script 等工具推荐算法）。无限额度令牌 `*_usd` 回报 1e8。`/dashboard/billing/subscription` 双形态等价。",
        "operationId": "getBillingSubscription",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "billing_subscription 应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSubscription"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/v1/dashboard/billing/usage": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "OpenAI legacy billing 用量查询",
        "description": "`{object:\"list\",total_usage}`（美分）；`daily_costs` 不返回。`/dashboard/billing/usage` 双形态等价。",
        "operationId": "getBillingUsage",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "billing usage 应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "total_usage": {
                      "type": "number",
                      "description": "已用金额（美分）"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/dashboard/billing/subscription": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "OpenAI legacy billing 配额查询（无 /v1 前缀形态）",
        "operationId": "getBillingSubscriptionNoPrefix",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "billing_subscription 应答",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSubscription"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    },
    "/dashboard/billing/usage": {
      "get": {
        "tags": [
          "余额与用量"
        ],
        "summary": "OpenAI legacy billing 用量查询（无 /v1 前缀形态）",
        "operationId": "getBillingUsageNoPrefix",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "responses": {
          "200": {
            "description": "billing usage 应答",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "const": "list"
                    },
                    "total_usage": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/TokenInvalid"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "OpenAI 惯例：Authorization: Bearer sk-…"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Anthropic 惯例（与 Bearer 等价）"
      },
      "geminiApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-goog-api-key",
        "description": "Gemini 惯例；亦可经 ?key= 查询参数"
      }
    },
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "description": "字符串或多模态分段数组"
          },
          "name": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_call_id": {
            "type": "string"
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "目标模型名称"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "max_tokens": {
            "type": "integer"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_choice": {},
          "response_format": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "$ref": "#/components/schemas/ChatMessage"
                },
                "finish_reason": {
                  "type": "string"
                }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": {
                "type": "integer"
              },
              "completion_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "SystemOneRequest": {
        "type": "object",
        "required": [
          "model",
          "questions"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "决策模型名（如 Kev-4B / jev-latest）"
          },
          "state": {
            "description": "决策上下文：字符串 / JSON / 数组"
          },
          "questions": {
            "type": "object",
            "description": "题集（键=题 ID）；≤32 题，整体 body ≤64KiB",
            "additionalProperties": {
              "type": "object",
              "required": [
                "type"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "noul",
                    "boolean",
                    "choice",
                    "score"
                  ],
                  "description": "noul/boolean=0..1 概率；choice=闭集单选；score=有序量表评分"
                },
                "instructions": {
                  "type": "string"
                },
                "criteria": {
                  "type": "object",
                  "additionalProperties": true
                },
                "options": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "choice 题闭集"
                },
                "legend": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "score 题量表"
                }
              }
            }
          }
        }
      },
      "SystemOneResponse": {
        "type": "object",
        "properties": {
          "answers": {
            "type": "object",
            "description": "按题 ID 返回：noul/boolean → {type, noul}; choice → {type, choice, probabilities, confidence}; score → {type, score, legend, 分布}"
          },
          "usage": {
            "type": "object",
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ImageGenerationRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "n": {
            "type": "integer",
            "default": 1,
            "maximum": 1,
            "description": "当前仅支持 1"
          },
          "size": {
            "type": "string",
            "enum": [
              "512x512",
              "1024x1024",
              "1024x1536",
              "1024x1792",
              "4096x4096"
            ],
            "description": "2^n 比例；其他比例静默降级 1024x1024"
          },
          "response_format": {
            "type": "string",
            "enum": [
              "url",
              "b64_json"
            ]
          },
          "output_format": {
            "type": "string",
            "enum": [
              "jpeg",
              "png",
              "webp"
            ],
            "default": "jpeg"
          },
          "watermark": {
            "type": "boolean"
          },
          "watermark_text": {
            "type": "string",
            "maxLength": 64,
            "description": "平台启用自定义水印时必传"
          },
          "prompt_extend": {
            "type": "boolean"
          }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {
            "description": "字符串或字符串数组"
          },
          "encoding_format": {
            "type": "string",
            "enum": [
              "float",
              "base64"
            ]
          }
        }
      },
      "OpenAIModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string",
            "enum": [
              "platform",
              "selfuse"
            ],
            "description": "platform=可服务平台聚合模型/auto 虚拟名/白名单内模型；selfuse=本人自用直调名与用户级聚合"
          },
          "supported_endpoint_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "additive 扩展字段"
          }
        }
      },
      "OpenAIModelList": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "success": {
            "type": "boolean",
            "description": "生态兼容保留字段"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OpenAIModel"
            }
          }
        }
      },
      "BillingSubscription": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "billing_subscription"
          },
          "has_payment_method": {
            "type": "boolean"
          },
          "soft_limit_usd": {
            "type": "number"
          },
          "hard_limit_usd": {
            "type": "number",
            "description": "= 总配额（余额+已用）折美元；无限额度回报 1e8"
          },
          "system_hard_limit_usd": {
            "type": "number"
          },
          "access_until": {
            "type": "integer",
            "description": "令牌过期时间（Unix 秒，永不过期为 0）"
          },
          "total_usage_usd": {
            "type": "number",
            "description": "已用美元；余额 = hard_limit_usd − total_usage_usd"
          }
        }
      },
      "TaskCreated": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "平台统一错误面（error{message,type,code} 或 success/message 形态，按线型）",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "token_invalid",
                  "client_rate_limited",
                  "service_unavailable"
                ]
              }
            }
          },
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "400 参数不合法（买家 7 码：invalid_request）",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "TokenInvalid": {
        "description": "401 密钥无效/缺失/删除（买家 7 码：token_invalid）",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ModelNotFound": {
        "description": "404 模型不存在或未绑定（买家 7 码：invalid_request）",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ClientRateLimited": {
        "description": "429 触发限流或超额（买家 7 码：client_rate_limited）",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "503 服务暂时不可用（买家 7 码：service_unavailable）",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    }
  }
}
