对话与文本

文本模型支持四种协议入口。同一枚令牌、同一个余额，客户端按自己习惯的协议接入即可。

协议	方法与路径	认证头
OpenAI	POST /v1/chat/completions	Authorization: Bearer
OpenAI Responses	POST /v1/responses	Authorization: Bearer
Claude	POST /v1/messages	x-api-key + anthropic-version
Gemini	POST /v1beta/models/{model}:generateContent	x-goog-api-key

具体模型支持哪些协议，见模型的"接口"列。

OpenAI 兼容

curl -sS -X POST "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "你是简洁的技术助手"},
      {"role": "user", "content": "解释一下什么是 embedding"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

流式

把 stream 设为 true，响应媒体类型为 text/event-stream，逐行读取 data: 后的 JSON，收到 data: [DONE] 结束：

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","model":"gpt-5.6-terra","choices":[{"index":0,"delta":{"content":"片段"},"finish_reason":null}]}

data: [DONE]

需要最后一个片段带用量时传 stream_options: {"include_usage": true}，上游不支持该字段时会被忽略。

多模态输入

content 可以是文本与图片对象组成的数组：

{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图的构图"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
      ]
    }
  ]
}

图片用公网 HTTPS 地址或 data: URL。模型不接受图片输入时，请求里的图片会被拒绝，能不能发图以模型发布的 input_modalities 为准。

工具调用

tools / tool_choice 遵循 OpenAI 格式，是否生效取决于所选模型。

Claude 原生

给 Claude Code、Anthropic SDK 这类客户端使用。Base URL 填 https://neartoken.cc（不要带 /v1，SDK 自己拼）：

curl -sS -X POST "$ROOT_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "写一个 Go 的快速排序"}]
  }'

Claude 协议支持的模型在模型中标记为 Claude。

OpenAI Responses

适合需要服务端保存响应、后台任务或事件流的新式客户端（Codex 等）：

curl -sS -X POST "$BASE_URL/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": "总结一下 Responses API 和 Chat Completions 的区别"
  }'

POST /v1/responses/compact 用于压缩上下文。WebSocket 客户端可用 wss://neartoken.cc/v1/responses。

Gemini 原生

模型名放在 URL 里，请求体用 contents / generationConfig：

curl -sS -X POST \
  "$ROOT_URL/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "用三句话介绍你自己"}]}],
    "generationConfig": {"temperature": 0.6}
  }'

流式用 streamGenerateContent?alt=sse。countTokens 未实现，会返回 404。

推理强度

部分模型可以控制思考深度，字段按协议区分：

协议	字段
OpenAI	reasoning_effort
Claude	thinking
Gemini	generationConfig.thinkingConfig

模型发布的可选档位以 GET /api/pricing 的 reasoning_levels 为准。不传就用模型默认档位；传了不支持的档位会被上游拒绝，不会静默降级。

上下文与输出上限

长对话的压实阈值应该来自模型发布的 context_window，不要凭经验写死。客户端可以在 GET /api/pricing 里读到每个模型的 context_window 和 max_tokens。

注意

• messages 至少一条 user 消息，model 和 messages 必填。
• 未知字段可能被忽略，也可能返回参数错误，以响应为准。
• 出错时不要根据错误文本猜别的模型名，只使用清单里的名称。
• 长对话、思考模型建议客户端超时不低于 300 秒。