{
  "openapi": "3.1.0",
  "info": {
    "title": "花椰菜 API Gateway",
    "summary": "OpenAI 兼容的大模型网关：对话、生图、视频，一个入口。",
    "description": "官方站点 https://api.colnt.com。OpenAI SDK 将 base_url 设为 https://api.colnt.com/v1，使用控制台颁发的 API Key。模型 ID 以 GET /v1/models 为准。本规范依据 2026-09-05 公开探测整理：标注 verified 的路径已在无密钥条件下被网关拦截；推理成功响应体需持有效 Key 复核。",
    "version": "1.0.0",
    "contact": {
      "name": "花椰菜",
      "url": "https://api.colnt.com"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://api.colnt.com",
      "description": "生产网关"
    }
  ],
  "tags": [
    { "name": "Discovery", "description": "可索引、无需密钥的发现接口" },
    { "name": "OpenAI", "description": "OpenAI 兼容推理" },
    { "name": "Google", "description": "Gemini / Generative Language 形态" },
    { "name": "Anthropic", "description": "Messages 形态" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getHealth",
        "summary": "存活检查",
        "x-geo-status": "verified",
        "responses": {
          "200": {
            "description": "服务可用",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" },
                "example": { "status": "ok" }
              }
            }
          }
        }
      }
    },
    "/setup/status": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getSetupStatus",
        "summary": "安装状态",
        "x-geo-status": "verified",
        "responses": {
          "200": {
            "description": "已完成安装",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SetupStatus" }
              }
            }
          }
        }
      }
    },
    "/api/v1/public/catalog": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getPublicCatalog",
        "summary": "公开能力目录",
        "description": "GEO 新增。部署后端前可先由静态文件或 nginx 别名提供 example JSON。",
        "x-geo-status": "candidate",
        "responses": {
          "200": {
            "description": "能力与文档链接",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicCatalog" }
              }
            }
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "tags": ["OpenAI"],
        "operationId": "listModels",
        "summary": "列出可用模型",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "responses": {
          "200": {
            "description": "OpenAI 风格模型列表（持 Key 后复核）",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ModelList" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createChatCompletion",
        "summary": "对话补全",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Chat completion（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/responses": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createResponse",
        "summary": "Responses API",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model"],
                "properties": {
                  "model": { "type": "string" },
                  "input": { "description": "输入文本或多模态内容" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Response object（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/images/generations": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createImage",
        "summary": "图像生成",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "model": { "type": "string" },
                  "prompt": { "type": "string" },
                  "n": { "type": "integer", "minimum": 1 },
                  "size": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "图像结果（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/images/edits": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "editImage",
        "summary": "图像编辑",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "responses": {
          "200": { "description": "图像结果（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/videos/generations": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createVideo",
        "summary": "视频生成",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": { "type": "string" },
                  "prompt": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "视频任务或结果（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/videos": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createVideoAlias",
        "summary": "视频生成（别名）",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "responses": {
          "200": { "description": "视频任务或结果（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/embeddings": {
      "post": {
        "tags": ["OpenAI"],
        "operationId": "createEmbedding",
        "summary": "文本向量",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input"],
                "properties": {
                  "model": { "type": "string" },
                  "input": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Embedding 列表（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": ["Anthropic"],
        "operationId": "createMessage",
        "summary": "Anthropic Messages 形态",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "responses": {
          "200": { "description": "Message（持 Key 后复核）" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/realtime": {
      "get": {
        "tags": ["OpenAI"],
        "operationId": "realtimeHandshake",
        "summary": "实时通道握手",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
        "responses": {
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1beta/models": {
      "get": {
        "tags": ["Google"],
        "operationId": "listGeminiModels",
        "summary": "Gemini 模型列表形态",
        "x-geo-status": "verified-auth-required",
        "security": [{ "BearerAuth": [] }, { "GoogleApiKey": [] }],
        "responses": {
          "401": {
            "description": "Gemini 信封 UNAUTHENTICATED",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GeminiError" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "控制台创建的 API Key"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "GoogleApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-goog-api-key"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "缺少或非法 API Key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/GatewayError" },
            "examples": {
              "missing": {
                "value": {
                  "code": "API_KEY_REQUIRED",
                  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
                }
              },
              "invalid": {
                "value": {
                  "code": "INVALID_API_KEY",
                  "message": "Invalid API key"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "example": "ok" },
          "name": { "type": "string", "example": "花椰菜" },
          "base_url": { "type": "string", "format": "uri" },
          "docs": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" }
        }
      },
      "SetupStatus": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "data": {
            "type": "object",
            "properties": {
              "needs_setup": { "type": "boolean", "example": false },
              "step": { "type": "string", "example": "completed" }
            }
          }
        }
      },
      "PublicCatalog": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "base_url": { "type": "string", "format": "uri" },
          "api_base": { "type": "string", "format": "uri" },
          "protocols": { "type": "array", "items": { "type": "string" } },
          "capabilities": { "type": "array", "items": { "type": "string" } },
          "auth": { "type": "array", "items": { "type": "string" } },
          "docs": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" },
          "llms": { "type": "string", "format": "uri" },
          "health": { "type": "string", "format": "uri" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "GatewayError": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "error": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "code": { "type": "string" },
              "message": { "type": "string" },
              "docs": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "GeminiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "status": { "type": "string" }
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "list" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "object": { "type": "string", "example": "model" },
                "owned_by": { "type": "string" }
              }
            }
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string" },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string" },
                "content": {}
              }
            }
          },
          "stream": { "type": "boolean" },
          "temperature": { "type": "number" }
        }
      }
    }
  }
}