{"openapi":"3.0.3","info":{"title":"API 分发平台","version":"1.0.0","description":"统一 API 网关：鉴权 / 限流 / 计量计费 / 多密钥 / 微信充值。所有 /v1/* 接口需在请求头携带 X-API-Key。"},"servers":[{"url":"http://localhost:9000","description":"本地服务"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"开发者 API Key"},"adminToken":{"type":"apiKey","in":"header","name":"x-admin-token","description":"管理员令牌"}}},"security":[{"apiKey":[]}],"tags":[{"name":"网关","description":"基础网关接口"},{"name":"真实 API","description":"转发第三方真实上游的接口"},{"name":"开发者门户","description":"开发者自助接口（注册/对账单/发票等）"},{"name":"管理后台","description":"管理员接口（需 x-admin-token）"}],"paths":{"/v1/hello":{"get":{"summary":"健康检查","operationId":"hello","tags":["网关"],"description":"返回服务状态，用于探活。","responses":{"200":{"description":"OK"},"401":{"description":"缺少/无效 API Key"}}}},"/v1/echo":{"get":{"summary":"回显","operationId":"echo","tags":["网关"],"description":"原样返回传入参数，便于联调。","parameters":[{"name":"msg","in":"query","description":"回显内容","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/v1/time":{"get":{"summary":"当前时间","operationId":"time","tags":["网关"],"description":"返回服务器当前时间。","responses":{"200":{"description":"OK"}}}},"/v1/weather":{"get":{"summary":"天气查询","operationId":"weather","tags":["真实 API"],"description":"转发 open-meteo，返回实时天气。","parameters":[{"name":"city","in":"query","description":"城市名（如 Beijing）","required":false,"schema":{"type":"string"}},{"name":"lat","in":"query","description":"纬度","required":false,"schema":{"type":"number"}},{"name":"lon","in":"query","description":"经度","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"天气数据"},"402":{"description":"余额不足"},"429":{"description":"限流"}}}},"/v1/ip":{"get":{"summary":"IP 归属地","operationId":"ip","tags":["真实 API"],"description":"转发 ipinfo，返回 IP 归属地。","responses":{"200":{"description":"IP 数据"}}}},"/v1/translate":{"get":{"summary":"翻译","operationId":"translate","tags":["真实 API"],"description":"转发 MyMemory 翻译引擎。","parameters":[{"name":"text","in":"query","description":"待翻译文本","required":true,"schema":{"type":"string"}},{"name":"to","in":"query","description":"目标语言代码（如 en/zh/ja）","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"译文"}}}},"/v1/chat":{"post":{"summary":"大模型对话","operationId":"chat","tags":["真实 API"],"description":"转发 MoMA（灵克）OpenAI 兼容对话接口（模型 tt-6-astra）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"模型名，默认 tt-6-astra"},"messages":{"type":"array","items":{"type":"object"},"description":"对话消息数组 [{role, content}]"}},"required":["messages"]}}}},"responses":{"200":{"description":"模型回复"},"402":{"description":"余额不足"},"429":{"description":"限流"}}}},"/portal/register":{"post":{"summary":"开发者注册","operationId":"register","tags":["开发者门户"],"security":[],"description":"注册新开发者并自动发放 API Key。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"开发者名称"},"plan":{"type":"string","enum":["free","pro","enterprise"],"description":"套餐"}},"required":["name"]}}}},"responses":{"200":{"description":"返回 apiKey"}}}},"/portal/invoice":{"post":{"summary":"开具发票","operationId":"issueInvoice","tags":["开发者门户"],"security":[],"description":"为「已支付」的充值订单开具电子发票（默认沙箱 provider）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"开发者 API Key"},"orderId":{"type":"string","description":"充值订单号"},"taxId":{"type":"string","description":"购方税号（可选）"}},"required":["key","orderId"]}}}},"responses":{"200":{"description":"发票已开具"},"409":{"description":"该订单已开票"}}},"get":{"summary":"查询发票","operationId":"getInvoice","tags":["开发者门户"],"security":[],"parameters":[{"name":"id","in":"query","description":"发票 ID","required":true,"schema":{"type":"string"}},{"name":"fmt","in":"query","description":"html 返回票面页","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"发票 JSON"}}}},"/portal/invoices":{"get":{"summary":"我的发票列表","operationId":"listInvoices","tags":["开发者门户"],"security":[],"parameters":[{"name":"key","in":"query","description":"开发者 API Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"发票列表"}}}},"/admin/invoice/issue":{"post":{"summary":"管理员代开发票","operationId":"adminIssueInvoice","tags":["管理后台"],"security":[{"adminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"devKey":{"type":"string"},"orderId":{"type":"string"},"taxId":{"type":"string"}},"required":["devKey","orderId"]}}}},"responses":{"200":{"description":"发票已开具"}}}},"/admin/invoice/void":{"post":{"summary":"作废发票","operationId":"adminVoidInvoice","tags":["管理后台"],"security":[{"adminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"responses":{"200":{"description":"已作废"}}}},"/admin/circuit_breakers":{"get":{"summary":"上游熔断器实时快照","operationId":"adminCircuitBreakers","tags":["管理后台"],"security":[{"adminToken":[]}],"description":"各真实上游（open-meteo / open-meteo-geo / ipinfo / mymemory / moma）的熔断状态、连续失败数、成功数、冷却剩余时间与最近错误。","responses":{"200":{"description":"熔断器列表（closed / open / half-open）"}}}},"/admin/provision_dev":{"post":{"summary":"为外部账号开通 API Key","operationId":"provisionDev","tags":["管理后台"],"security":[{"adminToken":[]}],"description":"汲木智能体服务端在用户注册后调用：为指定 externalUid 生成并分配 API Key（幂等，重复调用返回同 Key）。需携带 PROVISION_TOKEN（x-admin-token）。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalUid":{"type":"string","description":"外部账号 ID（汲木 users.id），幂等键"},"account":{"type":"string","description":"登录账号（可选，便于识别）"},"name":{"type":"string","description":"开发者名称（可选）"},"email":{"type":"string","description":"邮箱（可选）"},"plan":{"type":"string","enum":["free","pro","enterprise"],"description":"套餐"},"source":{"type":"string","description":"来源标识，默认 jimu"}},"required":["externalUid"]}}}},"responses":{"200":{"description":"返回 apiKey（existed 标识是否幂等命中）"},"400":{"description":"缺少 externalUid"},"403":{"description":"来源 IP 不在白名单"}}}}}}