DOCS OPENAPI 3.1

中转站 API 文档

完整描述 24 个公开操作：中转站身份、自定义充值、业务 Key、文档端点和 9 个固定 credits 接口。每个操作展开后都包含认证、Origin、CSRF、字段、示例、成功响应、特定错误、重试与幂等。公开 canonical 为 https://api.funaokeji.com；loopback 的 /gateway 仅用于本地验收兼容。

下载 OpenAPI JSON读取 llms.txt
01

快速开始

身份、充值和业务调用之间保持明确边界。

  1. 验证身份POST /v1/auth/send-code 后提交 challenge、短信码、待验证恢复邮箱与强密码。
  2. 准备 credits在 /console#recharge 输入整数元；服务端按 ¥1=10 credits 固化订单快照。
  3. 创建业务 Key只选择实际需要的 scope；明文只显示一次。
  4. 幂等调用业务请求携带 Bearer Key 和唯一 Idempotency-Key。
02

OneAuth 身份共享，Gateway 账务隔离

只共享不可变身份 subject 与验证能力，不共享钱包或商业账户。

SHARED

身份

中国大陆手机号验证、不可变 OneAuth subject、待验证/已验证恢复邮箱状态、登录会话交接。

ISOLATED

Gateway 资产

personal project、credits、充值订单、usage、ledger 与业务 API Key。

NEVER MERGED

其他账务

OneAuth 通用余额、注册奖励和其他产品账务都不能变成 Gateway credits。

验证码是 6 位 CSPRNG 数字，5 分钟有效，60 秒冷却，最多 5 次错误；重发使旧码失效，成功后一次性消费。发送接口永不回显验证码。

注册时填写的恢复邮箱保持待验证：不获得登录权、不占用地址。只有独立验证后才成为唯一登录身份；待验证邮箱与未知邮箱登录失败一致。

03

自定义充值与透明价格

没有固定套餐或折扣档位；所有计算使用整数分。

汇率¥1.00 = 10 credits
允许金额¥1 – ¥10,000
步长¥1 整数元
当前支付LOCAL-SIMULATED
操作路径scopecredits人民币折算
04

扣费、幂等与不确定结果

所有业务接口遵循同一状态机。

reserve→settle或release或manual_review
  • reserve：转发前从当前 Gateway project 预留固定 credits。
  • settle：确认成功后只结算一次；相同幂等键与请求指纹重放不二次扣费。
  • release：确认未转发或适配器失败时释放预留。
  • manual_review：结果不确定时保持预留，禁止自动或盲目重试。
  • 402 / 409：402 表示 credits 不足；409 表示幂等键复用冲突或状态冲突。
05

24 个公开操作

搜索可按路径、operationId、标签、用途或错误码快速定位；展开接口可查看完整合同。内部 ops、control 与邀请接口不在这里。

运行时 provider：模型 alibaba-cloud / deepseek / doubao；真挑与购物 douyin / jd / pinduoduo。

06

核心调用示例

示例使用占位 Key，不包含真实凭据。

cURL
curl -X POST https://api.funaokeji.com/v1/models/chat \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: request-unique-id" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"hello"}'
JavaScript
const response = await fetch("https://api.funaokeji.com/v1/models/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${gatewayApiKey}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ prompt: "hello" })
});
Python
import requests, uuid

response = requests.post(
    "https://api.funaokeji.com/v1/models/chat",
    headers={
        "Authorization": f"Bearer {gateway_api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"prompt": "hello"},
    timeout=10,
)
07

错误处理

错误响应使用稳定 code；客户端不得从 message 猜测可重试性。

202

结果不确定，hold 保留为 manual_review。

400

字段、格式或金额合同无效。

401

登录会话或业务 Key 无效。

402

当前 project 可用 credits 不足。

403 / 404

权限拒绝，或 owner 资源不可见。

408 / 413

请求体超时或过大。

409

幂等键或资源状态冲突。

421 / 429

Host 被拒绝，或进入限流窗口。

500 / 502 / 503

内部、上游合同或依赖失败。

08

运行与生产边界

当前文档描述本地候选的已实现合同，不等于外部能力已上线。

NOT_RUN：真实短信送达、生产 OneAuth、真实支付/退款/发票、真实供应商、DNS、TLS、WAF、CDN、生产部署与流量切换。

双主域：api.funaokeji.com 只承载 Gateway；peipao.funaokeji.com 承载独立服务前台。其他 Host 均 fail closed。