其他模型 API 详细教程

本文介绍 Gemini、Claude、GPT、Grok 系列模型的接口地址、参数说明与调用示例。

本文介绍 TOKEN 平台的 29 个模型及其调用方式。请求时使用清单中的平台模型名称，并保留大小写；官方 ID 用于查阅厂商文档。API 密钥使用平台生成的 Token。

通用接口形式

接口支持矩阵

模型系列	Chat Completions	Responses	Messages
Claude（10 个）	支持	—	支持
GPT（8 个）	支持	支持	—
Gemini（8 个）	支持	—	—
Grok（3 个）	支持	—	—

全部 29 个模型支持 Chat Completions；OpenAI 模型还支持 Responses，Claude 模型还支持 Messages。扩展能力与参数遵循对应模型的官方规范，接口支持不代表所有型号都支持全部工具、媒体类型或采样参数。「—」表示本教程不使用该组合。

接口	平台请求地址	鉴权
Chat Completions	`POST https://token.matpool.com/v1/chat/completions`	`Authorization: Bearer YOUR_API_TOKEN`
Responses	`POST https://token.matpool.com/v1/responses`	`Authorization: Bearer YOUR_API_TOKEN`
Messages	`POST https://token.matpool.com/v1/messages`	`x-api-key: YOUR_API_TOKEN` 和 `anthropic-version: 2023-06-01`

三种协议不要混用

项目	Chat Completions	Responses	Messages
输入	`messages` 数组	`input` 字符串或输入项数组	`messages` 数组
系统提示	`messages` 中的 `system` / `developer`，依模型选择	顶层 `instructions`	顶层 `system`
输出上限	`max_completion_tokens`；部分型号使用 `max_tokens`，不同时发送两者	`max_output_tokens`	必填 `max_tokens`
函数定义	嵌套于 `tools[].function`	平铺于 `tools[]`	`name`、`description`、`input_schema`
工具返回	`role: "tool"` 与 `tool_call_id`	`function_call_output` 与 `call_id`	`tool_result` 与 `tool_use_id`
结构化输出	`response_format`	`text.format`	`output_config.format`
文本响应	`choices[].message.content`	`output` 内的 `output_text` 块；SDK 提供 `output_text` 聚合属性	`content` 内的 `text` 块
完成状态	`finish_reason`	`status`	`stop_reason`

temperature、top_p、top_k、stop、seed 的支持范围与默认值因模型而异。基础示例省略这些可选字段，使用时按具体型号的参数规范添加。

当前支持的模型列表

平台支持以下 29 个模型：Claude 10 个、GPT 8 个、Gemini 8 个、Grok 3 个。型号定位参考官方文档，平台价格见文末模型广场。

Anthropic Claude（10）

模型名称	模型定位与特征
Claude-Fable-5.1	面向高难度推理与长周期智能体任务；当前 Fable 型号。官方总览
Claude-Fable-5	前代 Fable；自适应思考始终开启，文本/图像输入、文本输出。型号页
Claude-Opus-5.5	面向长时间运行的智能体编程和知识工作；当前 Opus 型号。官方总览
Claude-Opus-5	前代 Opus，支持自适应思考与百万 token 上下文；适合已有 Opus 工作流。型号页
Claude-Opus-4.8	改善编程、智能体执行与协作能力的 Opus 更新版。官方发布
Claude-Opus-4.7	前代 Opus；文本/图像输入，支持自适应思考及百万 token 上下文。型号页
Claude-Opus-4.6	强化编程规划、调试、长任务与大型代码库处理。官方发布
Claude-Sonnet-4.6	前代 Sonnet；支持自适应思考、文本/图像输入及百万 token 上下文。型号页
Claude-Sonnet-5	前代 Sonnet；默认启用自适应思考，文本/图像输入、文本输出。型号页
Claude-Sonnet-5.5	兼顾速度与智能，适合需要较快响应的复杂应用。官方总览

OpenAI GPT（8）

模型名称	模型定位与特征
GPT-6.1-Sol	以较低成本处理复杂工作，性能接近 Astra。官方总览
GPT-6-Astra	OpenAI 面向最苛刻任务的最高能力模型。官方总览
GPT-6-Sol	为复杂编程和智能体工作流设计；文本/图像输入、文本输出。型号页
GPT-6-Luna	面向目标明确、高调用量任务的高效率模型。官方总览
GPT-5.6-Luna	为成本敏感工作负载优化；文本/图像输入、文本输出。型号页
GPT-5.6-Sol	面向复杂专业工作的 GPT-5.6 旗舰；文本/图像输入、文本输出。型号页
GPT-5.6-Terra	平衡智能与成本；文本/图像输入、文本输出。型号页
GPT-OSS-120B	Apache 2.0 许可的开放权重模型，可在单张 H100 上部署；文本输入/输出，不应套用其他 GPT 的图像能力。型号页

Google Gemini（8）

模型名称	模型定位与特征
Gemini-3.1-Flash	通过平台 Chat Completions 接口进行文本问答、摘要和内容生成。
Gemini-3.1-Pro	增强推理、事实依据、编程与智能体流程；官方文档以 3.1 Pro Preview 介绍。型号页
Gemini-3.5-Flash	强调速度与成本的前代 Flash。型号页
Gemini-3.5-Flash-Lite	快速、经济，面向高吞吐工作负载。官方总览
Gemini-3.6-Flash	前代 Flash，平衡速度与多模态能力，适用于智能体及日常任务。官方总览
Gemini-3.7-Flash	前代多模态推理模型，支持 low、medium、high 思考级别。型号页
Gemini-3.8-Flash	面向长时间软件工程、自主智能体和企业工作流的 Flash 型号。官方总览
Gemini-4-Argon	旗舰推理模型，面向高难度推理与长上下文任务。官方总览

xAI Grok（3）

模型名称	使用场景
Grok-4.5	通过平台 Chat Completions 接口进行文本问答、摘要和内容生成。
Grok-4.6	通过平台 Chat Completions 接口进行文本问答、摘要和内容生成。
Grok-4.7	通过平台 Chat Completions 接口进行文本问答、摘要和内容生成。

一、Google Gemini 模型

1.1 型号与官方参考

模型名称	官方 ID 参考	选型与使用提示
Gemini-3.1-Flash	—	文本问答、摘要与内容生成。
Gemini-3.1-Pro	`gemini-3.1-pro-preview`	复杂推理、编程与智能体任务。来源
Gemini-3.5-Flash	`gemini-3.5-flash`	前代速度/成本取向的 Flash 模型。来源
Gemini-3.5-Flash-Lite	`gemini-3.5-flash-lite`	高吞吐、成本敏感任务。来源
Gemini-3.6-Flash	`gemini-3.6-flash`	日常多模态及智能体工作。来源
Gemini-3.7-Flash	`gemini-3.7-flash`	支持 low/medium/high 思考级别，不支持 minimal。来源
Gemini-3.8-Flash	`gemini-3.8-flash`	长周期软件工程、自主智能体与企业任务。来源
Gemini-4-Argon	`gemini-4-argon`	高难度推理及长上下文任务。来源

1.2 基础文本与思考配置

基础平台请求：

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Gemini-3.8-Flash",
    "messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
  }'

Google OpenAI 兼容文档明确区分原始 HTTP 请求与 Python SDK 的 extra_body：

HTTP JSON 中，Google 专有配置位于 extra_body.google.thinking_config。
Python OpenAI SDK 的 extra_body 参数会合并到请求正文，因此需要再包含一个名为 extra_body 的键。不能盲目把 HTTP 正文中的 google 提升到顶层。
reasoning_effort 与 thinking_level / thinking_budget 不要一起发送；支持的级别、是否可关闭思考依型号而定，不把某型号规则套用到整个系列。
include_thoughts 请求的是可提供的思考摘要，不保证返回完整内部推理过程。

以下请求使用 Google 官方兼容格式设置思考级别与摘要：

json
{
  "model": "Gemini-3.8-Flash",
  "messages": [{"role": "user", "content": "比较两种缓存失效策略的优缺点"}],
  "extra_body": {
    "google": {
      "thinking_config": {
        "thinking_level": "low",
        "include_thoughts": true
      }
    }
  }
}

对应 Python 写法：

python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MATPOOL_API_KEY"],
                base_url="https://token.matpool.com/v1")
response = client.chat.completions.create(
    model="Gemini-3.8-Flash",
    messages=[{"role": "user", "content": "比较两种缓存失效策略的优缺点"}],
    extra_body={
        "extra_body": {
            "google": {
                "thinking_config": {
                    "thinking_level": "low",
                    "include_thoughts": True,
                }
            }
        }
    },
)
print(response.choices[0].message.content)

1.3 多模态、工具与结构化输出

官方 3.1 Pro Preview、3.5 Flash、3.7 Flash 型号页列出文本、图像、视频、音频、PDF 输入及文本输出。不同接口的媒体结构不同；使用 Chat Completions 时遵循 Google 的 OpenAI 兼容协议。
图片、普通函数工具与 JSON Schema 示例见「五、共用调用示例」。媒体 MIME、大小、分辨率与安全策略遵循具体型号的限制。
将普通函数命名为 googleSearch 或 codeExecution，只是在声明一个需要客户端执行的函数，不会自动启用 Google 托管搜索或代码执行。
Google 的搜索和代码执行文档分别给出内置工具声明；它们属于对应原生 API 的工具协议，不能直接搬入 TOKEN Chat Completions。使用托管工具时，应采用官方为所选接口定义的工具格式。

二、Claude 模型

2.1 型号与官方参考

模型名称	官方 ID 参考	选型与使用提示
Claude-Fable-5.1	`claude-fable-5-1`	高难度推理、长周期智能体；思考始终开启。来源
Claude-Fable-5	`claude-fable-5`	前代 Fable；始终启用自适应思考，文本/图像输入。来源
Claude-Opus-5.5	`claude-opus-5-5`	长周期编程与知识工作；思考始终开启，官方默认 effort 为 medium。来源
Claude-Opus-5	`claude-opus-5`	前代 Opus；自适应思考、百万 token 上下文。来源
Claude-Opus-4.8	`claude-opus-4-8`	编程、智能体执行及协作增强。来源
Claude-Opus-4.7	`claude-opus-4-7`	前代 Opus；自适应思考、文本/图像输入。来源
Claude-Opus-4.6	`claude-opus-4-6`	长任务、代码库分析与调试。来源
Claude-Sonnet-4.6	`claude-sonnet-4-6`	前代 Sonnet；支持自适应思考。来源
Claude-Sonnet-5	`claude-sonnet-5`	默认自适应思考；文本/图像输入、文本输出。来源
Claude-Sonnet-5.5	`claude-sonnet-5-5`	兼顾速度与智能；文本/图像输入、文本输出。来源

2.2 Messages 基础请求

Claude 可使用 Chat Completions 或 Messages。使用 Anthropic 特有内容块、思考与工具协议时推荐 Messages。初始系统提示放在顶层，输出上限显式提供：

bash
curl https://token.matpool.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "Claude-Sonnet-4.6",
    "max_tokens": 1024,
    "system": "请用简洁中文回答。",
    "messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
  }'

以下为响应结构示意；ID 和用量以服务端返回值为准：

json
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "Claude-Sonnet-4.6",
  "content": [{"type": "text", "text": "量子计算利用量子态及其演化处理信息。"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 20, "output_tokens": 18}
}

2.3 思考、搜索与缓存边界

Anthropic 当前原生思考模式是 thinking: {"type":"adaptive"}，深度由 output_config.effort 控制。Opus 4.6 / Sonnet 4.6 的手动预算模式已弃用，后续型号不接受旧 enabled + budget_tokens 模式，见官方总览。
Messages 使用 output_config.effort 设置思考强度，而不是 Chat 的 reasoning_effort；强度档位不是固定的 token 数量。
Sonnet 5 不接受非默认采样值。其他型号也应遵循各自参数规范，不要给整个系列统一设置 temperature。
Anthropic 联网搜索使用 tools 中的版本化服务端工具定义，不使用 Chat 的 web_search_options。
Prompt Caching 需要遵循缓存控制、最小长度与命中条件。图片输入按 Messages 的 URL 或 Base64 source 格式提供。
Messages 思考响应使用内容块。多轮对话应保留完整内容块及签名；不要只保存可见文字后再提交工具续轮。

下面使用自适应思考与流式输出；复杂任务可按预算提高输出上限，遇 max_tokens 停止原因应处理截断：

bash
curl -N https://token.matpool.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "Claude-Opus-4.6",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {"type": "adaptive"},
    "output_config": {"effort": "high"},
    "messages": [{"role": "user", "content": "比较两种消息队列架构的可靠性与成本，并给出结论"}]
  }'

Messages 流式返回 Anthropic SSE 事件，如 message_start、content_block_start、content_block_delta、message_delta、message_stop，还可能有 ping/error。不能按 Chat 的 choices[].delta 解析；HTTP 200 后也需处理流内错误。

三、GPT 模型

3.1 型号与官方参考

模型名称	官方 ID 参考	选型与使用提示
GPT-6.1-Sol	`gpt-6.1-sol`	复杂工作、接近 Astra 的性能与较低成本。来源
GPT-6-Astra	`gpt-6-astra`	最苛刻的高难度任务。来源
GPT-6-Sol	`gpt-6-sol`	复杂编程和智能体流程。来源
GPT-6-Luna	`gpt-6-luna`	明确、集中的高调用量任务。来源
GPT-5.6-Luna	`gpt-5.6-luna`	成本敏感负载。来源
GPT-5.6-Sol	`gpt-5.6-sol`	复杂专业工作。来源
GPT-5.6-Terra	`gpt-5.6-terra`	智能与成本平衡。来源
GPT-OSS-120B	`gpt-oss-120b`	开放权重、文本输入/输出模型；不要发送图像输入。来源

3.2 基础请求

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "GPT-6.1-Sol",
    "messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
  }'

3.3 参数与端点选择

GPT 模型支持 Chat Completions 与 Responses。使用 OpenAI 内置工具或 Responses 输入/输出结构时，选择 /v1/responses。
Chat 的 max_completion_tokens 与 Responses 的 max_output_tokens 都包含可见输出及推理 token，不等于最终文本字数。采样参数和思考强度依具体型号而定。
不要在 Chat Completions 的 tools 中发送 Responses 搜索工具。 Responses 内置搜索使用 tools: [{"type": "web_search"}]；Chat 搜索有自己的型号与参数要求，见官方搜索指南。
JSON Schema 的 Chat 入口是 response_format，Responses 的入口为 text.format，见结构化输出指南。

3.4 Responses 基础请求

Responses 使用 input 而不是 messages。详见文本生成指南与Responses API 参考。

字段	类型	用途
`model`	字符串，必填	平台模型名称，如 `GPT-6.1-Sol`
`input`	字符串或输入项数组	简单文本直接传字符串；多轮可传包含 `role`、`content` 的消息数组，也可加入工具调用与结果项
`instructions`	字符串，可选	当前请求的系统级指令；使用 `previous_response_id` 续轮时，上一轮指令不会自动沿用，应按需重新提供
`max_output_tokens`	整数，可选	生成的总输出 token 上限，包含推理 token
`stream`	布尔值，可选	默认 `false`；设为 `true` 返回 SSE 事件流

bash
curl https://token.matpool.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "GPT-6.1-Sol",
    "instructions": "请用简洁中文回答。",
    "input": "用一句话介绍量子计算",
    "max_output_tokens": 2048,
    "stream": false
  }'

响应结构示意（省略其他字段，ID 与用量仅作示例）：

json
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "GPT-6.1-Sol",
  "output": [{
    "id": "msg_example",
    "type": "message",
    "role": "assistant",
    "status": "completed",
    "content": [{
      "type": "output_text",
      "text": "量子计算利用量子态及其演化处理信息。",
      "annotations": []
    }]
  }],
  "usage": {"input_tokens": 20, "output_tokens": 18, "total_tokens": 38}
}

output 可同时包含推理、工具调用和消息项。处理 HTTP JSON 时，应遍历 type: "message" 项的 content，读取 type: "output_text" 的 text，不要固定取 output[0].content[0]。官方 Python/JavaScript SDK 提供 response.output_text 聚合文本，它不是所有原始 HTTP 响应都带有的顶层字段。

先检查 status：incomplete 时查看 incomplete_details，failed 时查看 error；同时处理消息内的 refusal 内容块。包含函数调用的响应需要执行工具续轮，而不是直接当作最终文本答案。

3.5 Responses 流式请求

bash
curl -N https://token.matpool.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "GPT-6.1-Sol",
    "instructions": "请用中文回答。",
    "input": "写一首四行的春日短诗",
    "max_output_tokens": 2048,
    "stream": true
  }'

-N 关闭 curl 输出缓冲。按 SSE 事件边界解析 JSON，读取 response.output_text.delta 事件的 delta 字段并拼接文本；不要使用 Chat 的 choices[].delta.content。监听 response.completed、response.incomplete、response.failed 及 error，并处理连接中断；没有收到完成事件不能视为成功。工具参数增量是独立事件，应与文本增量分开处理。参阅流式响应指南。

3.6 Responses 工具与结构化输出

Responses 的函数定义是平铺结构，没有 Chat 的 function 包装层。以下完整请求正文发送到 /v1/responses：

json
{
  "model": "GPT-6.1-Sol",
  "input": "查询上海当前天气",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "查询指定城市的当前天气",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": "auto"
}

检查 output 中 type: "function_call" 的项，解析其 arguments 并执行经过授权的白名单函数。将完整 output 追加至输入历史，再为每个调用加入 type: "function_call_output"、匹配的 call_id 及字符串 output，连同工具定义再次请求。工具结果必须来自实际执行；模型只生成调用参数，不会替客户端执行自定义函数。内置工具则按官方定义声明，如 {"type":"web_search"}，并遵循所选型号的工具支持范围。

结构化输出使用 text.format，name、schema、strict 直接放在 format 下，不再嵌套 json_schema：

json
{
  "model": "GPT-6.1-Sol",
  "input": "提取：书名《三体》，作者刘慈欣。",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "book",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "author": {"type": "string"}
        },
        "required": ["title", "author"],
        "additionalProperties": false
      }
    }
  }
}

读取输出文本后再进行 JSON 解析。拒绝和达到输出上限的响应应单独处理，不能当作完整 schema 结果使用。

四、Grok 模型

4.1 型号与使用场景

模型名称	使用场景
Grok-4.5	文本问答、摘要与内容生成。
Grok-4.6	文本问答、摘要与内容生成。
Grok-4.7	文本问答、摘要与内容生成。

4.2 最小兼容请求

使用 Chat Completions 发送文本对话请求：

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Grok-4.5",
    "messages": [{"role": "user", "content": "用一句话介绍量子计算"}]
  }'

基础文本请求只需指定 model 与 messages。扩展参数按具体型号的官方规范设置，参阅 xAI 模型文档与推理能力指南。

五、共用调用示例

以下 Chat 示例使用 Gemini-3.8-Flash。 替换模型时，所用功能应在该型号的支持范围内；GPT-OSS-120B 是文本模型，不能接收图像。

5.1 流式输出

bash
curl -N https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Gemini-3.8-Flash",
    "messages": [{"role": "user", "content": "写一首四行的春日短诗"}],
    "stream": true
  }'

Chat 流按 SSE 逐事件读取，文本增量通常位于 choices[].delta.content；不是每个事件都带文本。工具调用参数需要按索引拼接，再做 JSON 解析及校验；处理终止标记、断线和错误，不把网络分块等同于完整 SSE 事件。

5.2 图片理解

图片 URL 必须能够被服务端访问；可将示例 URL 替换为自己的公开图片地址。

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Gemini-3.8-Flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片的主要内容"},
        {"type": "image_url", "image_url": {"url": "https://cdn.matpool.com/images/159cfc58_opt_token1.png"}}
      ]
    }]
  }'

Chat 的 Base64 图片一般采用 image_url.url 中的 data URL；Messages 则使用 type: "image" 和 source。不可混用。Messages URL 图片正文示例：

json
{
  "model": "Claude-Sonnet-4.6",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image", "source": {"type": "url", "url": "https://cdn.matpool.com/images/159cfc58_opt_token1.png"}},
      {"type": "text", "text": "描述这张图片的主要内容"}
    ]
  }]
}

5.3 Function Calling 与结果回传

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Gemini-3.8-Flash",
    "messages": [{"role": "user", "content": "查询上海当前天气"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

函数声明不会自动执行天气服务。客户端需完成以下步骤：

检查 choices[0].message.tool_calls，不要假定一定会调用工具。
将 assistant 消息完整追加到历史中，保留兼容层返回的必要扩展字段；解析 function.arguments JSON 并按 schema 校验。
仅执行白名单函数，验证城市等参数；有副作用的操作先取得用户授权。
对每个调用追加一条 role: "tool" 消息，其中 tool_call_id 必须匹配实际响应 ID，content 为实际执行结果字符串。
将完整历史和工具定义再次提交模型；处理多个调用、执行错误和循环次数上限。

回传消息的结构示意如下；其中 ID 和天气是占位数据，不可作为真实查询结果：

json
{
  "role": "tool",
  "tool_call_id": "call_example",
  "content": "{\"city\":\"上海\",\"temperature_c\":22,\"source\":\"示例数据，非实时天气\"}"
}

Claude 的 Messages 工具流程需改用 tool_use / tool_result 块，不能将上述 role: "tool" 直接放入 Messages。

5.4 结构化输出

下例使用 Chat response_format.json_schema，不是 Responses 的 text.format，也不是 Anthropic Messages 的 output_config.format。使用该型号支持的 JSON Schema 子集；客户端仍应处理拒绝、截断并验证结果。

bash
curl https://token.matpool.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "Gemini-3.8-Flash",
    "messages": [{"role": "user", "content": "提取：书名《三体》，作者刘慈欣。只返回符合 schema 的 JSON。"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "book",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "author": {"type": "string"}
          },
          "required": ["title", "author"],
          "additionalProperties": false
        }
      }
    }
  }'

对严格 schema，每个 object（包括嵌套 object）声明 additionalProperties: false，并按支持的 schema 子集设置 required。
json_object 只约束 JSON 形式，不等于遵守任意 JSON Schema；提示词也应明确要求 JSON。
先检查拒绝、内容过滤及长度截断，再解析文本并验证 schema；不要对 null 内容或不完整文本直接解析。

六、推荐的 SDK 配置

安装对应官方 SDK，并通过环境变量 MATPOOL_API_KEY 注入平台密钥；不要提交真实密钥到代码仓库或浏览器前端。以下示例使用平台接口地址。

6.1 OpenAI SDK：基址包含 `/v1`

Python：

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MATPOOL_API_KEY"],
    base_url="https://token.matpool.com/v1",
)
response = client.chat.completions.create(
    model="GPT-6.1-Sol",
    messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
)
print(response.choices[0].message.content)

Node.js（ES module，例如保存为 .mjs）：

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MATPOOL_API_KEY,
  baseURL: "https://token.matpool.com/v1",
});
const response = await client.chat.completions.create({
  model: "GPT-6.1-Sol",
  messages: [{ role: "user", content: "用一句话介绍量子计算" }],
});
console.log(response.choices[0]?.message.content);

6.2 OpenAI SDK：Responses

使用与 Chat 相同的 SDK 客户端和 /v1 基址，改为调用 responses.create。

Python：

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MATPOOL_API_KEY"],
    base_url="https://token.matpool.com/v1",
)
response = client.responses.create(
    model="GPT-6.1-Sol",
    instructions="请用简洁中文回答。",
    input="用一句话介绍量子计算",
    max_output_tokens=2048,
)
if response.status != "completed":
    raise RuntimeError(f"输出未正常完成：{response.status}")
print(response.output_text)

Node.js（ES module）：

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MATPOOL_API_KEY,
  baseURL: "https://token.matpool.com/v1",
});
const response = await client.responses.create({
  model: "GPT-6.1-Sol",
  instructions: "请用简洁中文回答。",
  input: "用一句话介绍量子计算",
  max_output_tokens: 2048,
});
if (response.status !== "completed") {
  throw new Error(`输出未正常完成：${response.status}`);
}
console.log(response.output_text);

output_text 聚合文本内容；若返回拒绝块或工具调用，按第 3.4、3.6 节处理，不要把空文本视作有效答案。

6.3 Anthropic SDK：基址不重复添加 `/v1`

官方 SDK 的 Messages 资源请求路径已经是 /v1/messages，因此这里设置域名根地址。不要再添加 /v1，以免拼成 /v1/v1/messages。依据：Python 资源源码、TypeScript SDK。

Python：

python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["MATPOOL_API_KEY"],
    base_url="https://token.matpool.com",
)
message = client.messages.create(
    model="Claude-Sonnet-4.6",
    max_tokens=1024,
    system="请用简洁中文回答。",
    messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
)
if message.stop_reason in ("max_tokens", "refusal"):
    raise RuntimeError(f"输出未正常完成：{message.stop_reason}")
for block in message.content:
    if block.type == "text":
        print(block.text)

Node.js（ES module）：

javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.MATPOOL_API_KEY,
  baseURL: "https://token.matpool.com",
});
const message = await client.messages.create({
  model: "Claude-Sonnet-4.6",
  max_tokens: 1024,
  system: "请用简洁中文回答。",
  messages: [{ role: "user", content: "用一句话介绍量子计算" }],
});
if (["max_tokens", "refusal"].includes(message.stop_reason)) {
  throw new Error(`输出未正常完成：${message.stop_reason}`);
}
for (const block of message.content) {
  if (block.type === "text") console.log(block.text);
}

SDK 会按其协议构造鉴权和版本头。处理 400 时先检查参数与协议，401/403 检查权限，404 检查路由和型号，429/5xx 使用有上限的重试；记录脱敏请求 ID，不记录密钥。

七、费用与错误处理

基础文本费用通常按输入、输出 token 分别计价，缓存写入/读取、推理 token、多媒体、搜索及执行工具可能另有计费规则。平台价格以模型广场及实际账单为准，不以厂商官方标价代替平台售价。

控制输出预算：按接口设置输出上限，为推理模型预留推理 token；截断时缩小任务或调整额度。
处理限流与故障：对 429 和可重试的 5xx 使用有上限的指数退避，不要无限重试参数错误。
保护凭据：密钥只存于服务端环境变量或密钥管理服务，日志仅记录脱敏请求信息。
保留协议内容：工具续轮保留必要消息、调用 ID 和思考签名；流式响应完整结束后再提交业务结果。

八、官方参考资料

Anthropic 模型总览：型号定位、模态与思考方式。
OpenAI 模型总览及各型号页：定位、模态与端点。
Google 模型总览及各型号页：型号定位与生命周期。
Google OpenAI 兼容 API：思考扩展、图像、流式、函数与结构化请求。
OpenAI 文本生成、Responses API、流式响应：请求与响应格式。
OpenAI 搜索、结构化输出：Chat 与 Responses 的工具及输出结构。
Google 搜索、代码执行：内置工具协议。
Anthropic Python SDK 资源源码、TypeScript SDK：Messages 请求路径与 SDK 使用。
xAI 模型文档、推理能力：型号与参数指南。

通用接口形式

接口支持矩阵

三种协议不要混用

当前支持的模型列表

Anthropic Claude（10）

OpenAI GPT（8）

Google Gemini（8）

xAI Grok（3）

一、Google Gemini 模型

1.1 型号与官方参考

1.2 基础文本与思考配置

1.3 多模态、工具与结构化输出

二、Claude 模型

2.1 型号与官方参考

2.2 Messages 基础请求

2.3 思考、搜索与缓存边界

三、GPT 模型

3.1 型号与官方参考

3.2 基础请求

3.3 参数与端点选择

3.4 Responses 基础请求

3.5 Responses 流式请求

3.6 Responses 工具与结构化输出

四、Grok 模型

4.1 型号与使用场景

4.2 最小兼容请求

五、共用调用示例

5.1 流式输出

5.2 图片理解

5.3 Function Calling 与结果回传

5.4 结构化输出

六、推荐的 SDK 配置

6.1 OpenAI SDK：基址包含 /v1

6.2 OpenAI SDK：Responses

6.3 Anthropic SDK：基址不重复添加 /v1

七、费用与错误处理

八、官方参考资料

6.1 OpenAI SDK：基址包含 `/v1`

6.3 Anthropic SDK：基址不重复添加 `/v1`