septmoon API
接入文档

一、开始使用

1. 准备接入信息

export SEPTMOON_BASE_URL="https://septmoon.cn"
export SEPTMOON_API_KEY="YOUR_API_KEY"

2. 鉴权方式

不要把 API Key 放进 URL 查询参数，也不要出现在前端代码、公开仓库、日志或截图中。

3. 获取可用模型

curl "$SEPTMOON_BASE_URL/v1/models" \
  -H "Authorization: Bearer $SEPTMOON_API_KEY"

{
  "object": "list",
  "data": [{ "id": "MODEL_ID", "object": "model" }]
}

Gemini 原生客户端使用 GET /v1beta/models 与 x-goog-api-key 请求头；若名称形如 models/MODEL_ID，调用时取 MODEL_ID 部分。

4. 接口选择

二、OpenAI API

OpenAI SDK Base URL：https://septmoon.cn/v1。支持下列兼容接口，不代表支持 OpenAI 官方平台全部 API。

1. Responses API

curl "$SEPTMOON_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $SEPTMOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "instructions": "你是一个简洁、准确的中文助手。",
    "input": "用一句话解释什么是大语言模型。",
    "max_output_tokens": 512
  }'

Python SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SEPTMOON_API_KEY"],
    base_url=os.environ["SEPTMOON_BASE_URL"].rstrip("/") + "/v1",
)
response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="用一句话解释什么是大语言模型。",
)
print(response.output_text)

2. Chat Completions API

curl "$SEPTMOON_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SEPTMOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role":"user","content":"你好，请介绍一下你自己。"}],
    "max_completion_tokens": 512
  }'

3. 其他接口

三、Claude API

兼容 Anthropic Messages API。Base URL 使用 https://septmoon.cn，不要重复追加 /v1。

创建消息

curl "$SEPTMOON_BASE_URL/v1/messages" \
  -H "x-api-key: $SEPTMOON_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "system": "你是一个简洁、准确的中文助手。",
    "messages": [{"role":"user","content":"你好，请用一句话介绍你自己。"}]
  }'

Python SDK

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["SEPTMOON_API_KEY"],
    base_url=os.environ["SEPTMOON_BASE_URL"].rstrip("/"),
)
message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=1024,
    messages=[{"role":"user","content":"你好，请介绍一下你自己。"}],
)
for block in message.content:
    if block.type == "text": print(block.text)

Token 计数

能力取决于 API Key 分组及上游；遇到 404 not_found_error 时跳过或使用本地估算。

四、Gemini API

同时提供 Gemini 原生协议与 OpenAI Chat Completions 兼容协议。原生请求使用 contents，响应使用 candidates。

原生生成内容

curl "$SEPTMOON_BASE_URL/v1beta/models/MODEL_ID:generateContent" \
  -H "x-goog-api-key: $SEPTMOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"解释什么是大语言模型。"}]}],
    "generationConfig": {"maxOutputTokens":512,"temperature":0.7}
  }'

Python SDK

import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["SEPTMOON_API_KEY"],
    http_options=types.HttpOptions(
        base_url=os.environ["SEPTMOON_BASE_URL"].rstrip("/"),
        api_version="v1beta",
    ),
)
response = client.models.generate_content(
    model=os.environ["GEMINI_MODEL"],
    contents="用一句话解释什么是大语言模型。",
)
print(response.text)

五、Grok API

使用 OpenAI 兼容 HTTP 协议。请使用绑定 Grok 或 xAI 分组的 API Key，新接入优先选择 Responses API。

媒体能力取决于分组权限、模型及上游账号，请先通过 /v1/models 确认。

六、流式响应

OpenAI Responses 流

curl -N "$SEPTMOON_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $SEPTMOON_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","input":"写一段产品介绍。","stream":true}'

按事件 type 分发，不要把所有 SSE data 都当纯文本。Chat Completions 增量通常位于 choices[0].delta.content；Gemini 文本通常位于 candidates[].content.parts[].text。

Claude 事件顺序

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop

七、错误码与重试

单次业务请求建议最多自动重试 3 次，并设置总超时。400、401、403 与已返回部分流内容的请求不要原样自动重试。

八、生产环境建议

排障日志

• 请求时间、本地请求 ID、接口与模型 ID。
• HTTP 状态码、错误 type / code、响应头请求 ID 和 Retry-After。
• 耗时、是否流式、是否收到部分内容。
• 不要记录完整 API Key、敏感提示词、文件原文或隐私数据。

九、官方参考资料

内容依据各厂商官方 API 规范，并结合 septmoon 当前网关路由、鉴权与协议转换调整 Base URL 和兼容说明。点击以下卡片可前往对应的官方开发文档。

免责声明

兼容网关不代表所有上游模型都支持官方接口中的每一个参数。模型能力、上下文长度、工具调用、图片、视频、结构化输出、缓存、推理参数与速率限制，以当前 API Key 返回的模型、控制台说明及实际上游响应为准。

厂商可能更新接口和 SDK。升级 SDK 或启用新参数前，请先在测试环境验证。