POST
/
v1
/
chat
/
completions
原生 OpenAI 格式(ChatCompletions)
curl --request POST \
  --url https://api.novawander.cn/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "temperature": 123,
  "stream": true,
  "max_tokens": 123,
  "top_p": 123
}
'
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

简介

通用文本对话接口,支持 OpenAI 兼容的大语言模型生成对话回答。通过统一的 API 接口,您可以调用 OpenAI、Claude、DeepSeek、Grok、通义千问等多个主流大模型。

认证

Authorization
string
必填
Bearer Token,如 Bearer sk-xxxxxxxxxx

请求参数

model
string
必填
模型标识,支持的模型包括:
  • OpenAI 系列:gpt-5.5、gpt-5.4、gpt-5.4-pro、gpt-5.4-mini、gpt-5.4-nano、gpt-4o 等
  • Claude 系列:claude-opus-4-8、claude-opus-4-7、claude-opus-4-6、claude-sonnet-4-5-20250929、claude-haiku-4-5-20251001 等
  • DeepSeek 系列:deepseek-v4-pro、deepseek-v4-flash、deepseek-v3-1-250821、deepseek-v3、deepseek-r1 等
  • Grok 系列:grok-4、grok-4-fast-reasoning、grok-3 等
  • Gemini 系列:gemini-3.1-pro-preview、gemini-3-pro-preview、gemini-3-flash-preview、nano-banana-pro 及其 -thinking/-nothinking / -thinking-<预算> / -thinking-low/-thinking-high 后缀变体
  • 国产模型系列:glm-5、glm-4.7、doubao-seed-1-8-251228(豆包 Seed 系列)、qwen3-coder-plus、kimi-k2.5 等
messages
array
必填
对话消息列表,每个元素包含 role(user/system/assistant)和 content
temperature
number
默认值:"0.7"
随机性控制,0-2,值越高回复越随机
stream
boolean
默认值:"false"
是否启用流式输出,返回 SSE 格式的分片数据
max_tokens
number
最大生成 token 数,控制回复长度
top_p
number
核采样参数,0-1,控制生成的多样性

基础示例

非流式请求
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手"},
      {"role": "user", "content": "请用中文简要介绍人工智能"}
    ],
    "temperature": 0.7
  }'
流式请求(SSE)
curl -N -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "stream": true,
    "messages": [
      {"role": "system", "content": "你是一个有用的助手"},
      {"role": "user", "content": "请用中文简要介绍人工智能"}
    ]
  }'
Python 示例
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.novawander.cn/v1"
)

# 非流式
completion = client.chat.completions.create(
    model="glm-5",
    messages=[
        {"role": "system", "content": "你是一个有用的助手"},
        {"role": "user", "content": "请用中文简要介绍人工智能"}
    ],
    temperature=0.7
)
print(completion.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="doubao-seed-1-8-251228",
    messages=[
        {"role": "user", "content": "请用中文简要介绍人工智能"}
    ],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

高级功能

工具调用(Functions / Tools)

支持 OpenAI 兼容的工具调用格式,适用于 GPT、Claude、DeepSeek、Grok、通义千问等模型。
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "上海的天气怎么样?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "根据城市获取天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

结构化输出(JSON Schema)

支持通过 response_format 参数控制输出格式,适用于 GPT、Claude、Grok 等模型。
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "Answer",
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "messages": [
      {"role": "user", "content": "返回一个包含 summary 字段的 JSON"}
    ]
  }'
严格的结构化输出建议降低 temperature 值(如 0.1-0.3),并设置合适的 max_tokens 以提升一致性。

思考能力

部分模型支持思考能力(Thinking/Reasoning),可以在生成回复时展示推理过程。不同模型的实现方式不同:
DeepSeek 模型支持通过 thinking 字段开启思考能力:
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "deepseek-v3-1-250821",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手"},
      {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
    ],
    "thinking": {"type": "enabled"}
  }'
  • 默认 thinking.type 为 "disabled",需要显式设置为 "enabled" 开启
  • 思考能力的输出形态可能因模型版本而异
  • 建议配合 stream: true 以获得更好的交互体验

通义千问扩展功能

通义千问模型支持搜索、语音识别等扩展功能,所有扩展参数需放入 parameters 对象中。
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "messages": [
      {"role": "user", "content": "请先检索近期关于费马大定理的常见误解,再回答"}
    ],
    "stream": true,
    "enable_thinking": true,
    "parameters": {
      "enable_search": true,
      "search_options": {
        "region": "CN",
        "recency_days": 30
      },
      "incremental_output": true
    }
  }'
通义千问的所有扩展参数(如 enable_search、search_options、asr_options、temperature、top_p 等)都需要放在 parameters 对象中,而不是请求体的顶层。

联网搜索功能

部分模型支持实时联网搜索,可以获取最新信息并在响应中包含引用来源。
Claude 模型不支持通过 web_search_options 参数开启网络搜索功能,所以使用只能通过tool工具调用实现,且可能因为网络和提示词等原因不稳定,详细看上面工具调用(Functions / Tools)。基础示例(展示工具调用流程):
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "最近关于人工智能的新闻有哪些?"},
      {
        "role": "assistant",
        "content": "我来帮你搜索一下最近关于人工智能的新闻。",
        "tool_calls": [
          {
            "id": "toolu_xxx",
            "type": "function",
            "function": {
              "name": "WebSearch",
              "arguments": "{\"query\": \"人工智能 最新新闻 2025\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "toolu_xxx",
        "name": "WebSearch",
        "content": "Web search results for query: \"人工智能 最新新闻 2025\"..."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'
带位置信息的示例(展示工具调用流程):
curl -X POST "https://api.novawander.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "上海今天的天气怎么样?"},
      {
        "role": "assistant",
        "content": "我来帮你搜索一下上海今天的天气情况。",
        "tool_calls": [
          {
            "id": "toolu_xxx",
            "type": "function",
            "function": {
              "name": "WebSearch",
              "arguments": "{\"query\": \"上海今天天气\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "toolu_xxx",
        "name": "WebSearch",
        "content": "Web search results for query: \"上海今天天气\"..."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium",
      "user_location": {
        "approximate": {
          "timezone": "Asia/Shanghai",
          "country": "CN",
          "region": "Shanghai",
          "city": "Shanghai"
        }
      }
    }
  }'
  • 搜索功能会增加响应时间和 token 消耗(包含搜索结果内容)
  • 搜索结果会在响应中自动包含引用来源
  • 支持的模型包括 Claude Sonnet 4、Claude 3 Opus 等
  • 在多轮对话中,工具调用和结果会在消息历史中可见,模型可以基于之前的搜索结果继续对话
稳定性说明:
  • 联网搜索功能依赖上游代理服务和外部搜索服务,可能存在以下不稳定性:
    • 网络波动:网络连接问题可能导致搜索请求超时或失败
    • 服务限制:搜索服务可能有频率限制、超时限制或临时不可用
    • 搜索结果质量:某些查询可能无法找到相关信息,或搜索结果质量不佳
    • 模型判断:模型会根据问题自动判断是否需要搜索,某些情况下可能不会触发搜索

GPT 文件输入(Responses API)

GPT-5 等模型支持文件输入功能,需要通过 /v1/responses 接口调用,而不是 /v1/chat/completions。
您可以通过链接外部网址上传 PDF 文件:
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.novawander.cn/v1/responses?api-version=2025-03-01-preview"
)

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "分析这封信,并总结其关键点"
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.example.com/document.pdf"
                }
            ]
        }
    ]
)
print(response.output_text)
  • 文件大小限制:单个文件不超过 50 MB,单个请求中所有文件总大小不超过 50 MB
  • 支持的模型:gpt-4o、gpt-4o-mini、gpt-5-chat 等支持文本和图像输入的模型

Grok 推理能力

Grok 模型(特别是 grok-4-fast-reasoning)支持推理能力。启用后,usage.completion_tokens_details.reasoning_tokens 会显示推理过程消耗的 token 数。详见下方 usage 字段说明。

usage 字段说明

调用 /v1/chat/completions 时,响应中的 usage 对象包含 token 用量统计。以下先介绍通用字段(普通对话模型场景),再说明仅在特定场景下才会出现非零值的专属字段。

通用字段

适用范围:GPT 系列、Claude 对话/思考模型、Gemini、DeepSeek 等经由 /v1/chat/completions 走文本对话场景。不包含仅在底层实际调用 Claude Messages 协议或图片生成模型时才出现的字段——那些见 特殊场景专属字段。
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752345600,
  "model": "gpt-5.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是模型的回复内容"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 85,
    "total_tokens": 205,

    "prompt_tokens_details": {
      "cached_tokens": 30,
      "cache_write_tokens": 5,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 42,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },

    "input_tokens": 120,
    "output_tokens": 85,
    "input_tokens_details": null
  }
}
字段什么时候会有值说明
prompt_tokens始终输入 token 总数
completion_tokens始终输出 token 总数
total_tokens始终prompt_tokens + completion_tokens
prompt_tokens_details.cached_tokens模型/渠道支持 prompt caching 时命中缓存、按缓存价计费的输入 token 数(OpenAI 原生缓存、Gemini 隐式缓存、Claude 缓存读取都会体现在这个字段)
prompt_tokens_details.cache_write_tokens仅 GPT-5.6 及以上、开启显式 prompt cache 时本次请求新写入缓存、按缓存写入价计费的 token 数
prompt_tokens_details.audio_tokens仅使用音频输入模型(如 gpt-4o-audio-preview)时输入中音频部分消耗的 token 数
prompt_tokens_details.text_tokens / image_tokens多数纯文本对话模型下为 0输入中文本 / 图片部分的 token 拆分,纯文本对话场景通常不会被填充,只是字段本身始终存在
completion_tokens_details.reasoning_tokens仅推理模型(GPT o1/o3/GPT-5 系列、Claude 开启扩展思考、Gemini thinking)时模型内部思考消耗的 token 数,不会出现在最终回复文本里,但按输出价计费
completion_tokens_details.audio_tokens仅使用音频输出模型时输出中音频部分消耗的 token 数
completion_tokens_details.accepted_prediction_tokens / rejected_prediction_tokens仅使用 OpenAI Predicted Outputs 功能时命中 / 未命中预测内容的 token 数;未命中的部分仍按输出价计费
completion_tokens_details.text_tokens / image_tokens纯文本对话场景下为 0见下方「关于 image_tokens」说明
input_tokens / output_tokens始终数值上等同于 prompt_tokens / completion_tokens,是为兼容部分上游协议保留的别名字段
input_tokens_details目前对话场景下基本为 null保留字段,普通对话请求不会填充
  • prompt_tokens_details / completion_tokens_details 这两个对象在响应里始终存在,即使内部子字段全是 0 也不会被省略;0 不代表「不支持」,只代表「这次请求没用到」。
  • completion_tokens_details.image_tokens(以及 prompt_tokens_details.image_tokens)留在通用文档里是因为字段结构固定存在,但真正被赋非零值只发生在特殊场景(Claude/图片生成模型),详见 特殊场景专属字段。
  • reasoning_tokens 是跨模型通用概念:无论底层是 OpenAI 推理模型、Claude 扩展思考还是 Gemini thinking,只要该次调用启用了「思考」能力,都会体现在这一个字段里。

特殊场景专属字段

以下字段只在特定情况下才会出现非零值:请求走的是 /v1/chat/completions,但网关内部实际把请求转换成了别的协议去调用上游(Claude Messages 协议 / 图片生成模型),转换回来的 usage 里就会带上这些「原生协议专属」的字段。

场景一:底层实际调用 Claude(/v1/chat/completions → /v1/messages)

用 OpenAI 格式请求一个 Claude 模型时,网关会把请求转成 Anthropic Messages 协议发给上游,再把 Claude 返回的 usage 转换回 OpenAI 格式。Claude 的缓存机制比 OpenAI 更细(按 5 分钟 / 1 小时两档 TTL 计费),这部分信息用下面几个专属字段承载:
"usage": {
  "prompt_tokens": 120,
  "completion_tokens": 85,
  "total_tokens": 205,
  "prompt_tokens_details": {
    "cached_tokens": 30,
    "cached_creation_tokens": 10
  },
  "completion_tokens_details": {
    "reasoning_tokens": 42
  },
  "claude_cache_creation_5_m_tokens": 8,
  "claude_cache_creation_1_h_tokens": 2
}
字段说明
prompt_tokens_details.cached_creation_tokens对应 Claude 的 cache_creation_input_tokens:本次请求为写入 prompt cache 而额外消耗的输入 token 数(这个总数会被下面两个字段按 TTL 拆分)
claude_cache_creation_5_m_tokens上面 cached_creation_tokens 中,按 5 分钟 TTL 档写入缓存的 token 数
claude_cache_creation_1_h_tokens上面 cached_creation_tokens 中,按 1 小时 TTL 档写入缓存的 token 数(该档位单价更高)
prompt_tokens_details.cached_tokens、completion_tokens_details.reasoning_tokens 在调用 Claude 模型时也会有值(分别对应 Claude 的缓存读取 token 数、扩展思考 token 数),但这两个字段是跨模型通用字段,已在 通用字段 中说明。

场景二:底层实际调用图片生成模型(/v1/chat/completions → /v1/images/generations 语义)

某些图片生成模型(如 Gemini 原生图片输出、gpt-image 系列)本来是走官方 /v1/images/generations 接口的 usage 结构(input_tokens/output_tokens + 按模态拆分),但当用户改用 /v1/chat/completions 直接对话式调用这些模型生成图片时,网关会把这部分信息映射进 chat 格式的 usage 里:
"usage": {
  "prompt_tokens": 50,
  "completion_tokens": 1290,
  "total_tokens": 1340,
  "prompt_tokens_details": {
    "text_tokens": 50,
    "image_tokens": 0
  },
  "completion_tokens_details": {
    "text_tokens": 0,
    "image_tokens": 1290
  },
  "generated_images": 1
}
字段说明
completion_tokens_details.image_tokens官方 /v1/images/generations 里的图片输出 token 数,映射进 chat 格式后落在这个字段,按图片计费比例(ImageCompletionRatio)计费
prompt_tokens_details.image_tokens输入侧包含图片时(如图片编辑/图生图)消耗的图片 token 数
generated_images上游实际生成的图片张数(按张计费的模型用这个数值而不是 token 数来计费,避免「请求 4 张但只出 1 张」多扣费)

场景三:渠道协议差异导致的字段

这两个字段不是「转换」出来的,而是特定渠道原样透传上游响应字段,正常使用主流模型基本不会遇到:
字段出现条件说明
prompt_cache_hit_tokens渠道是 DeepSeek,且上游按 DeepSeek 自己的字段名返回缓存信息DeepSeek 官方 API 用 prompt_cache_hit_tokens 而不是 cached_tokens 表达缓存命中;网关会把它同步映射进通用的 prompt_tokens_details.cached_tokens,但原始字段也会保留在顶层
cost渠道是 OpenRouter,且上游在响应里带了美元成本OpenRouter 专属字段,普通渠道(官方 OpenAI/Claude/Gemini 等)不会出现

响应格式

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "回复内容..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}
usage 各字段的完整说明见上方 usage 字段说明。

错误处理

异常类型触发场景返回信息
AuthenticationErrorAPI密钥无效或未授权错误:API密钥无效或未授权
NotFoundError模型不存在或不被支持错误:模型 [model] 不存在或不被支持
APIConnectionError网络中断或服务器未响应错误:无法连接到API服务器
APIError请求格式错误等服务端异常API请求失败:[错误详情]

支持的模型系列

OpenAI 系列

  • GPT-5.5、GPT-5.4 系列(5.4 / Pro / Mini / Nano)、GPT-4o、GPT-4o Mini

Claude 系列(Anthropic)

  • Claude Sonnet 4、Claude 3 Opus、Claude 3 Haiku

DeepSeek 系列

  • DeepSeek V3、DeepSeek R1

Grok 系列(xAI)

  • Grok-4、Grok-3、Grok-3-fast、Grok-4-fast-reasoning

通义千问系列(Qwen)

  • Qwen3-omni-flash 等

豆包 Seed 系列(Doubao)

  • doubao-seed-1-8-251228 等

其他模型

  • Gemini 系列、GLM 系列(含 glm-5)、Kimi 系列等
完整模型列表请查看 模型信息页面。

注意事项

  • messages 列表中 system 角色用于设定模型行为,user 角色为用户提问
  • 多轮对话需追加历史记录(包含 assistant 角色的回复)
  • 依赖 openai 库:pip install openai
  • 不同模型对某些功能的支持程度可能不同,建议在使用前查看具体模型的文档
  • 使用流式输出可以提升首字响应时间和交互体验
  • 工具调用需要做好超时与重试机制,避免阻塞模型响应
  • 通义千问的扩展参数必须放在 parameters 对象中

相关资源

常见问题

查看对话接口的常见问题解答

模型列表

查看所有支持的模型信息