{
  "openapi": "3.1.0",
  "info": {
    "title": "Furries.World Web Intelligence API",
    "version": "1.0.0",
    "description": "实时网页搜索、抓取与格式化、多模态视觉理解、深度研究。认证方式为 Bearer API Key；金额单位为人民币分（cents）。",
    "contact": {
      "name": "Furries.World Support",
      "email": "support@furries.world",
      "url": "https://furries.world/docs"
    }
  },
  "servers": [
    { "url": "https://furries.world", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Search", "description": "实时网页搜索与带引用回答" },
    { "name": "Extract", "description": "网页抓取、清洗与格式化" },
    { "name": "Vision", "description": "图片描述、OCR 与结构化视觉分析" },
    { "name": "Research", "description": "多源交叉验证的研究简报" },
    { "name": "Account", "description": "账户、余额与用量" },
    { "name": "Meta", "description": "公开元数据" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fw_live_...",
        "description": "在控制台创建的 API Key。完整密钥只显示一次。"
      }
    },
    "schemas": {
      "Billing": {
        "type": "object",
        "required": ["requests", "credits_charged", "credits_remaining", "currency"],
        "properties": {
          "requests": { "type": "integer" },
          "prompt_tokens": { "type": "integer" },
          "output_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" },
          "credits_charged": { "type": "integer", "description": "本次扣费，单位：分。", "example": 15 },
          "credits_remaining": { "type": "integer", "description": "调用后的余额，单位：分。", "example": 185 },
          "currency": { "type": "string", "const": "CNY" },
          "price_cny": { "type": "string", "example": "¥0.15" }
        }
      },
      "Source": {
        "type": "object",
        "required": ["title", "url", "authority"],
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "snippet": { "type": "string" },
          "summary": { "type": "string" },
          "site_name": { "type": ["string", "null"] },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "authority": { "type": "integer", "minimum": -1, "maximum": 4 },
          "relevance": { "type": "number", "minimum": 0, "maximum": 3 },
          "content": { "type": "string", "description": "仅在 include_content=true 时返回，最长约 12,000 字符。" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code"],
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string", "examples": ["invalid_request_error", "authentication_error", "billing_error", "rate_limit_error", "service_error"] },
              "code": { "type": "string", "examples": ["invalid_request", "invalid_api_key", "insufficient_balance", "no_results"] },
              "param": { "type": ["string", "null"] },
              "request_id": { "type": "string" }
            }
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "minLength": 1, "maxLength": 128, "example": "2026 年 AI Agent 的关键进展" },
          "count": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 },
          "mode": { "type": "string", "enum": ["fast", "answer"], "default": "fast" },
          "include_content": { "type": "boolean", "default": false },
          "language": { "type": "string", "enum": ["zh", "en"] }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["request_id", "object", "results", "usage"],
        "properties": {
          "request_id": { "type": "string" },
          "object": { "type": "string", "const": "search" },
          "created": { "type": "integer" },
          "query": { "type": "string" },
          "mode": { "type": "string", "enum": ["fast", "answer"] },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } },
          "answer": { "type": "string", "description": "mode=answer 时的带引用回答。" },
          "model": { "type": "string" },
          "usage": { "$ref": "#/components/schemas/Billing" }
        }
      },
      "ExtractRequest": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri", "maxLength": 8192, "description": "公开的 http(s) 网页地址。与 query 至少提供一个。" },
          "query": { "type": "string", "maxLength": 256, "description": "检索主题。与 url 至少提供一个。" },
          "format": { "type": "string", "enum": ["markdown", "text", "json"], "default": "markdown" },
          "schema": { "type": "object", "description": "format=json 时约束输出结构，最大 8KB。" },
          "instructions": { "type": "string", "maxLength": 1500 },
          "language": { "type": "string", "enum": ["zh", "en", "auto"] }
        }
      },
      "ExtractResponse": {
        "type": "object",
        "required": ["request_id", "object", "format", "output", "sources", "usage"],
        "properties": {
          "request_id": { "type": "string" },
          "object": { "type": "string", "const": "extraction" },
          "created": { "type": "integer" },
          "format": { "type": "string", "enum": ["markdown", "text", "json"] },
          "output": {
            "oneOf": [
              { "type": "string" },
              { "type": "object", "additionalProperties": true },
              { "type": "array", "items": {} }
            ],
            "description": "Markdown/text 时为字符串，json 时为解析后的 JSON。"
          },
          "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } },
          "model": { "type": "string" },
          "usage": { "$ref": "#/components/schemas/Billing" }
        }
      },
      "VisionRequest": {
        "type": "object",
        "properties": {
          "image_url": { "type": "string", "maxLength": 8192, "description": "公开图片 URL 或 data URI。与 image_base64 互斥。" },
          "image_base64": { "type": "string", "description": "原始 Base64 图片数据，需要 media_type。解码后最大 9MB。" },
          "media_type": { "type": "string", "enum": ["image/jpeg", "image/png", "image/gif", "image/webp"] },
          "prompt": { "type": "string", "maxLength": 3000 },
          "format": { "type": "string", "enum": ["text", "json"], "default": "text" },
          "schema": { "type": "object", "description": "JSON 模式下的结构约束，最大约 6KB。" },
          "detail": { "type": "string", "enum": ["low", "high", "original", "auto"], "default": "auto" }
        }
      },
      "VisionResponse": {
        "type": "object",
        "required": ["request_id", "object", "format", "output", "usage"],
        "properties": {
          "request_id": { "type": "string" },
          "object": { "type": "string", "const": "vision" },
          "created": { "type": "integer" },
          "format": { "type": "string", "enum": ["text", "json"] },
          "output": { "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }] },
          "model": { "type": "string" },
          "usage": { "$ref": "#/components/schemas/Billing" }
        }
      },
      "ResearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "minLength": 1, "maxLength": 256 },
          "language": { "type": "string", "enum": ["zh", "en"] }
        }
      },
      "ResearchResponse": {
        "type": "object",
        "required": ["request_id", "object", "output", "sources", "usage"],
        "properties": {
          "request_id": { "type": "string" },
          "object": { "type": "string", "const": "research" },
          "created": { "type": "integer" },
          "query": { "type": "string" },
          "output": {
            "type": "object",
            "required": ["title", "executive_summary", "key_findings", "conclusion", "confidence"],
            "properties": {
              "title": { "type": "string" },
              "executive_summary": { "type": "string" },
              "key_findings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "finding": { "type": "string" },
                    "evidence": { "type": "string" },
                    "source_ids": { "type": "array", "items": { "type": "integer" } }
                  }
                }
              },
              "conflicting_views": { "type": "array", "items": { "type": "string" } },
              "open_questions": { "type": "array", "items": { "type": "string" } },
              "practical_implications": { "type": "array", "items": { "type": "string" } },
              "conclusion": { "type": "string" },
              "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
            }
          },
          "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } },
          "model": { "type": "string" },
          "usage": { "$ref": "#/components/schemas/Billing" }
        }
      },
      "Me": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "const": "account" },
          "user": {
            "type": "object",
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "email": { "type": "string", "format": "email" },
              "display_name": { "type": "string" }
            }
          },
          "balance_cents": { "type": "integer" },
          "balance_cny": { "type": "string" },
          "api_key": {
            "type": "object",
            "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }
          }
        }
      },
      "UsageItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "endpoint": { "type": "string" },
          "status": { "type": "string", "enum": ["succeeded", "failed", "pending"] },
          "price_cents": { "type": "integer" },
          "price_cny": { "type": "string" },
          "model": { "type": "string" },
          "prompt_tokens": { "type": "integer" },
          "output_tokens": { "type": "integer" },
          "latency_ms": { "type": "integer" },
          "request_id": { "type": "string" },
          "error_code": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "PricingItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "price_cents": { "type": "integer" },
          "price_cny": { "type": "string" }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "统一 API 错误。失败调用不收费。",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      }
    }
  },
  "paths": {
    "/v1/search": {
      "post": {
        "tags": ["Search"],
        "summary": "实时网页搜索",
        "description": "搜索实时互联网。mode=fast 返回结构化结果；mode=answer 额外生成带引用回答。价格：fast ¥0.05，answer ¥0.15。",
        "operationId": "searchWeb",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }
        },
        "responses": {
          "200": {
            "description": "搜索成功",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/extract": {
      "post": {
        "tags": ["Extract"],
        "summary": "网页提取与格式化",
        "description": "抓取网页或按主题搜索，再输出 Markdown、纯文本或符合 Schema 的 JSON。价格：¥0.15/次。",
        "operationId": "extractWeb",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractRequest" } } }
        },
        "responses": {
          "200": {
            "description": "提取成功",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/vision": {
      "post": {
        "tags": ["Vision"],
        "summary": "多模态视觉理解",
        "description": "图片描述、OCR、截图/图表分析与 JSON 提取。价格：¥0.10/次。",
        "operationId": "understandImage",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionRequest" } } }
        },
        "responses": {
          "200": {
            "description": "视觉分析成功",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisionResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/research": {
      "post": {
        "tags": ["Research"],
        "summary": "深度研究简报",
        "description": "多源搜索、阅读与交叉验证，输出结构化研究简报。价格：¥0.30/次。",
        "operationId": "researchTopic",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRequest" } } }
        },
        "responses": {
          "200": {
            "description": "研究完成",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["Account"],
        "summary": "查询账户与余额",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "账户信息",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": ["Account"],
        "summary": "查询最近用量",
        "operationId": "getUsage",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "用量列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "type": "string", "const": "list" },
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageItem" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/pricing": {
      "get": {
        "tags": ["Meta"],
        "summary": "公开价格表",
        "security": [],
        "operationId": "getPricing",
        "responses": {
          "200": {
            "description": "价格表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "type": "string", "const": "pricing" },
                    "currency": { "type": "string", "const": "CNY" },
                    "unit": { "type": "string" },
                    "minimum_topup_cents": { "type": "integer" },
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/PricingItem" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}