端点总表

API 端点总表

> 大模型网关全量端点总表：OpenAI 兼容协议为主入口，同时直连 Anthropic 与 Gemini 原生协议，覆盖实时语音、异步批量、绘图视频与 MCP 工具调用，全部端点共用同一把密钥与同一套限流。

认证与公共约定

各端点可用的模型不同：对话用 endpoint_types 含 chat 的模型，向量化 / 图像用对应场景的模型（在模型广场按端点类型筛选）。密钥若绑定了端点场景，跨场景调用会返回 403 key_scene_mismatch。

核心推理端点

realtime 握手认证二选一：Authorization: Bearer 握手头（Node / Python 客户端推荐），或 Sec-WebSocket-Protocol: openai-insecure-api-key.<密钥> 子协议（浏览器 WebSocket 无法自定义请求头时使用）。

对话补全示例（非流式）

curl https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手"},
      {"role": "user", "content": "用一句话介绍统一网关"}
    ]
  }'

智能路由（model = "auto"）

平台管理员开启智能路由后，把 model 填成 "auto"，网关在你的可用模型中自动选型（按质量 / 速度 / 成本评分）。客户端无需任何其他改动，调用形态与对话补全完全一致。

原生协议入口（Anthropic / Gemini）

除 OpenAI 兼容格式外，平台直接暴露两种原生协议入口：请求体与响应体按各自官方协议处理，平台内部自动完成格式适配与模型路由，调度、配额、计费链路与 OpenAI 入口完全一致。

Anthropic Messages 协议（/v1/messages，认证支持 x-api-key 头或 Authorization: Bearer）：

curl https://api.example.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "your-model-name",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话介绍统一网关"}]
  }'

Gemini 原生协议（/v1beta/models/{model}:generateContent，认证支持 x-goog-api-key 头或 ?key= 查询参数）：

curl "https://api.example.com/v1beta/models/your-model-name:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $API_KEY" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "用一句话介绍统一网关"}]}]
  }'

批量处理（Batch API）

离线大批量任务的完整闭环，五步全用同一把密钥：

# ① 准备任务文件（JSONL：每行一个子请求，custom_id 自定便于对账）
#    {"custom_id":"task-001","method":"POST","url":"/v1/chat/completions",
#     "body":{"model":"your-model-name","messages":[{"role":"user","content":"翻译：你好"}]}}

# ② 上传（purpose 固定 batch；单文件 ≤64MB / ≤1 万行 / 单行 ≤128KB，坏行整批拒收带行号）
curl "https://api.example.com/v1/files" -H "Authorization: Bearer $API_KEY" \
  -F "purpose=batch" -F "file=@tasks.jsonl"
# → {"id":"file-abc123",...}  记下 id

# ③ 创建批任务（endpoint 仅 /v1/chat/completions 或 /v1/embeddings）
curl "https://api.example.com/v1/batches" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_file_id":"file-abc123","endpoint":"/v1/chat/completions","metadata":{"job":"nightly-eval"}}'
# → {"id":"batch-xyz",...}  completion_window 上限 24h

# ④ 跟踪进度（进度 = 子请求计数真值）
curl "https://api.example.com/v1/batches/batch-xyz" -H "Authorization: Bearer $API_KEY"

# ⑤ 取结果（成功/失败分开两份文件）
curl "https://api.example.com/v1/files/<output_file_id>/content" -H "Authorization: Bearer $API_KEY"

绘图 / 视频任务（MJ 兼容端点）

绘图与视频走 MJ 兼容端点：POST 提交任务，GET 查询进度。提交计数，轮询查询不计数——查询走本地任务表，不产生上游调用，客户端可以放心高频轮询。

• 提交绘图：POST /mj/submit/imagine（响应含任务号，result 字段即任务 ID）
• 变换 / 放大等后续动作：POST /mj/submit/action（携带任务号与动作序号）
• 视频生成：POST /mj/submit/video 提交，同样经 fetch 查询
• 查询进度：GET /mj/task/{id}/fetch（不计数）——status 到达 SUCCESS 后 imageUrl 即成品地址
• 认证沿用 Authorization: Bearer；为兼容 midjourney-proxy 生态，也接受 mj-api-secret 头

任务相关的绘图 / 视频记录与产物预览，在使用日志的「绘图」「任务」分区可查。

MCP 工具调用

平台聚合的 MCP 工具服务走独立端点 POST /mcp（Streamable HTTP，单端点 JSON-RPC 2.0），用与模型调用同一把 sk- 密钥（Bearer 认证同源）。管理员接入的各 MCP 服务器工具在此聚合暴露，工具名带服务前缀 {服务名}__{工具名}。

三步用法（握手 → 列目录 → 调用）：

# ① initialize 握手（协议版本协商；不消耗额度）
curl https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'

# ② tools/list 列出你可用的全部工具（前缀聚合；不消耗额度）
curl https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# ③ tools/call 调用（name 须带 {服务名}__ 前缀；仅此方法计数）
curl https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"服务名__工具名","arguments":{ ... }}}'

任务插件端点

平台支持管理员安装任务插件扩展专属任务端点（如特定厂商的视频、数字人等）。对调用方而言，插件端点与 /v1 用同一把 API 密钥、同一套鉴权与限流，无任何额外凭证。插件注册的路径、方法与请求体格式以管理台「扩展插件」详情页公示为准——不同插件端点不同，平台不设统一约定。调用同样产生使用日志，可按任务 ID 追踪进度与产物。

错误响应结构

推理接口（/v1/*）的错误响应统一为 OpenAI 兼容结构，code 为机器可读错误码：

{
  "error": {
    "message": "密钥当日调用次数已达上限（1000 次/日）",
    "type": "switchyard_error",
    "code": "daily_request_limit_exceeded"
  }
}

按 code（而非 message 文案）编写客户端分支逻辑；限流类（429）建议指数退避重试；明确拒绝类（403 越权）不应重试，应先修正请求或配置。全部错误码含义与排障建议见错误码总表。