API 端点与协议

域名

域名	用途	是否走 CDN	说明
api.modexflow.cc	调 API 用这个	灰云直连	客户端指向这里，低延迟（~350ms TTFB）
www.modexflow.cc	管理控制台	橙云 CF	面板、登录、账单、日志
docs.modexflow.cc	本文档	橙云 CF	静态文档站

别搞混

客户端 一律用 api.modexflow.cc。用 www. 也能通，但会绕道 CF 全球边缘（慢 3-5 倍）。

支持的协议

OpenAI 兼容（推荐）

Base URL: https://api.modexflow.cc/v1

按 OpenAI Chat Completions 协议，凡是能填 base_url 的 OpenAI SDK / 客户端都能直接用。

端点	说明
POST /v1/chat/completions	聊天，支持 stream: true
POST /v1/completions	补全（旧接口，不推荐）
GET /v1/models	当前令牌可用的模型列表
POST /v1/embeddings	向量嵌入（如果对应上游支持）
POST /v1/images/generations	文生图（如果对应上游支持）
POST /v1/audio/transcriptions	语音转文字
POST /v1/audio/speech	文字转语音

Anthropic 原生

Base URL: https://api.modexflow.cc

对 Anthropic 官方 SDK / Claude Code 保持完全兼容。

端点	说明
POST /v1/messages	Anthropic Messages API
POST /v1/messages?beta=true	Beta 特性（如工具、扩展缓存）

用法：环境变量把 ANTHROPIC_BASE_URL 指到 https://api.modexflow.cc 即可。

Google Gemini 原生

Base URL: https://api.modexflow.cc

端点	说明
POST /v1beta/models/{model}:generateContent	单次生成
POST /v1beta/models/{model}:streamGenerateContent	流式生成

鉴权

所有请求都要带 Authorization: Bearer sk-你的-token 头。

一些客户端会用其他 header 名（比如 Anthropic SDK 用 x-api-key）—— 我们兼容，两个都收：

Authorization: Bearer sk-xxxxx      # OpenAI 风格（推荐）
x-api-key:     sk-xxxxx              # Anthropic 风格

请求示例

Chat Completions

curl https://api.modexflow.cc/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role":"user","content":"hi"}]
  }'

Streaming (SSE)

curl -N https://api.modexflow.cc/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role":"user","content":"hi"}],
    "stream": true
  }'

Anthropic Messages

curl https://api.modexflow.cc/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"hi"}]
  }'

List models

curl https://api.modexflow.cc/v1/models \
  -H "Authorization: Bearer $KEY"

响应头（我们会附加的）

Header	含义
x-new-api-version	网关版本
x-oneapi-request-id	请求全链路 ID，反馈问题时贴这个
via: 1.1 Caddy	经过 Caddy 反代（源站直连时可见）

超时策略

• 建立 TCP+TLS 连接：客户端超时可以设短（10s 内足够）
• 等首字节 (TTFB)：Claude/GPT 首字节一般 1-8s，长 prompt 可能更久，客户端超时至少给 30s
• 整个请求 (含流式)：网关上限 30 分钟，覆盖 Codex 长任务、Claude 大文档处理
• HTTP/2 keep-alive：默认开，长连接会被复用

用 SNI 直连源 IP？

技术上可以：

curl --resolve api.modexflow.cc:443:43.161.243.77 https://api.modexflow.cc/...

但没必要——api.modexflow.cc 本身就是灰云直连，DNS 已经指到源 IP。用域名就等于直连。

状态页

https://www.modexflow.cc/api/status 返回一个 JSON，success: true 表示网关健康。可用于给你的监控系统做 uptime 探测。

想要更详细的每个模型/渠道的健康状态，联系管理员开放监控页。