{
  "openapi": "3.0.3",
  "info": {
    "title": "黑蜂AI情感 API",
    "description": "黑蜂AI情感 (BlackBee AI) 高情商回复 REST API：生成回复、情感分析、配额查询。Base URL: https://api.blackbeeai.love",
    "version": "1.0.0",
    "contact": {
      "name": "黑蜂AI情感开发者支持",
      "url": "https://blackbeeai.love/developers.html"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    { "url": "https://api.blackbeeai.love", "description": "Production" },
    { "url": "https://api-staging.blackbeeai.love", "description": "Staging" }
  ],
  "tags": [
    { "name": "reply", "description": "高情商回复生成" },
    { "name": "analyze", "description": "情感意图分析" },
    { "name": "quota", "description": "配额管理" },
    { "name": "async", "description": "异步任务" }
  ],
  "paths": {
    "/api/v1/reply": {
      "post": {
        "tags": ["reply"],
        "summary": "生成高情商回复",
        "description": "输入对方消息 + 场景上下文，生成高情商回复。支持 standard / fast / perfect 三种模式。",
        "operationId": "createReply",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReplyRequest" },
              "example": {
                "mode": "perfect",
                "message": "你不会是见色起意吧",
                "context": "暧昧期，她刚发过来",
                "scene": "ambiguous",
                "reply_count": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReplyResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    },
    "/api/v1/reply/async": {
      "post": {
        "tags": ["async"],
        "summary": "异步生成回复（长任务）",
        "description": "适合完美版等耗时较长的任务。立即返回 task_id，完成后通过 webhook 回调或主动查询。",
        "operationId": "createReplyAsync",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReplyRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务已创建",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "integer", "example": 0 },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": { "type": "string", "example": "tsk_abc123" },
                        "status": { "type": "string", "enum": ["queued", "running"] }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/analyze": {
      "post": {
        "tags": ["analyze"],
        "summary": "情感意图分析",
        "description": "只分析情感与意图，不生成回复。",
        "operationId": "analyzeMessage",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["message"],
                "properties": {
                  "message": { "type": "string", "description": "对方消息原文" },
                  "context": { "type": "string", "description": "上下文/场景说明" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "integer", "example": 0 },
                    "data": { "$ref": "#/components/schemas/AnalyzeResult" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/quota": {
      "get": {
        "tags": ["quota"],
        "summary": "查询剩余配额",
        "operationId": "getQuota",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "integer", "example": 0 },
                    "data": {
                      "type": "object",
                      "properties": {
                        "quota": {
                          "type": "object",
                          "properties": {
                            "standard": { "type": "integer" },
                            "fast": { "type": "integer" },
                            "perfect": { "type": "integer" }
                          }
                        },
                        "expire_at": { "type": "string", "format": "date-time" },
                        "tier": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/task/{task_id}": {
      "get": {
        "tags": ["async"],
        "summary": "查询异步任务状态",
        "operationId": "getTask",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "任务状态" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "通过产品内「开发者中心 → 创建密钥」生成 API Key。"
      }
    },
    "schemas": {
      "ReplyRequest": {
        "type": "object",
        "required": ["mode", "message"],
        "properties": {
          "mode": {
            "type": "string",
            "enum": ["standard", "fast", "perfect"],
            "description": "standard 30-45秒深度推演，fast 约3秒，perfect 深度推演+多策略对比"
          },
          "message": { "type": "string", "description": "对方消息原文" },
          "context": { "type": "string", "description": "关系阶段、上下文背景" },
          "scene": {
            "type": "string",
            "enum": ["chat", "ambiguous", "dating", "humor", "conflict", "social", "work", "breakup", "proposal"]
          },
          "reply_count": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 }
        }
      },
      "ReplyResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "data": {
            "type": "object",
            "properties": {
              "replies": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": { "type": "string" },
                    "score": { "type": "number", "format": "float" },
                    "eq_analysis": { "type": "string" }
                  }
                }
              },
              "request_id": { "type": "string" },
              "mode": { "type": "string" },
              "tokens_used": { "type": "integer" }
            }
          }
        }
      },
      "AnalyzeResult": {
        "type": "object",
        "properties": {
          "emotion": { "type": "string", "example": "frustrated" },
          "intensity": { "type": "number", "format": "float", "minimum": 0, "maximum": 1 },
          "underlying_need": { "type": "string" },
          "relationship_stage": { "type": "string" },
          "suggested_strategy": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "未授权或 API Key 无效",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": { "type": "integer", "example": 401 },
                "msg": { "type": "string", "example": "invalid api key" }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "触发频率限制",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": { "type": "integer", "example": 429 },
                "msg": { "type": "string", "example": "rate limit exceeded" }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "服务器错误",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": { "type": "integer", "example": 500 },
                "msg": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}