原生 OpenAI 格式（ChatCompletions）

curl --request POST \
  --url https://api.gravitex.ai/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
}
'

import requests

url = "https://api.gravitex.ai/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "temperature": 123,
    "stream": True,
    "max_tokens": 123,
    "top_p": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    messages: [{}],
    temperature: 123,
    stream: true,
    max_tokens: 123,
    top_p: 123
  })
};

fetch('https://api.gravitex.ai/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'messages' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'stream' => true,
    'max_tokens' => 123,
    'top_p' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gravitex.ai/v1/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "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
  }
}

POST

chat

completions

原生 OpenAI 格式（ChatCompletions）

curl --request POST \
  --url https://api.gravitex.ai/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
}
'

import requests

url = "https://api.gravitex.ai/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "temperature": 123,
    "stream": True,
    "max_tokens": 123,
    "top_p": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    messages: [{}],
    temperature: 123,
    stream: true,
    max_tokens: 123,
    top_p: 123
  })
};

fetch('https://api.gravitex.ai/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'messages' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'stream' => true,
    'max_tokens' => 123,
    'top_p' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.gravitex.ai/v1/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "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、通义千问等多个主流大模型。

认证

string

必填

Bearer Token，如 Bearer sk-xxxxxxxxxx

请求参数

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 等

array

必填

对话消息列表，每个元素包含 role（user/system/assistant）和 content

number

默认值:"0.7"

随机性控制，0-2，值越高回复越随机

boolean

默认值:"false"

是否启用流式输出，返回 SSE 格式的分片数据

number

最大生成 token 数，控制回复长度

number

核采样参数，0-1，控制生成的多样性

基础示例

非流式请求

curl -X POST "https://api.gravitex.ai/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.gravitex.ai/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.gravitex.ai/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.gravitex.ai/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"
  }'

模型返回 tool_calls 后，需要执行工具并将结果回传给模型：

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "上海的天气怎么样？"},
      {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_xxx",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"上海\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_xxx",
        "content": "{\"temp\":\"22°C\",\"condition\":\"多云\",\"aqi\":53}"
      }
    ]
  }'

tool_call_id 必须与第一阶段返回的 ID 一致
工具执行失败时应返回可读的错误信息，避免阻塞后续补全
第二阶段也支持流式输出

结构化输出（JSON Schema）

支持通过 response_format 参数控制输出格式，适用于 GPT、Claude、Grok 等模型。

curl -X POST "https://api.gravitex.ai/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
通义千问
Gemini

DeepSeek 模型支持通过 thinking 字段开启思考能力：

curl -X POST "https://api.gravitex.ai/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 以获得更好的交互体验

通义千问支持深度思考功能，需要配合流式输出：

curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "stream": true,
    "enable_thinking": true,
    "parameters": {
      "incremental_output": true
    },
    "messages": [
      {"role": "system", "content": "你是一名优秀的数学家"},
      {"role": "user", "content": "汉诺塔的公式是啥"}
    ]
  }'

将推理过程内联到 content：如果客户端不展示 reasoning_content，可以使用 gravitex_thinking_to_content: true 将推理内容内联到 content 中：

curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "stream": true,
    "enable_thinking": true,
    "gravitex_thinking_to_content": true,
    "parameters": {
      "incremental_output": true
    },
    "messages": [
      {"role": "user", "content": "汉诺塔的公式是啥"}
    ]
  }'

通义千问的深度思考功能必须配合 stream: true 使用。如果设置了 enable_thinking: true 但 stream: false，系统会自动关闭深度思考以避免上游报错。

完整 Gemini OpenAI 兼容说明（字段映射、extra_body、usage、思维链等）见 Gemini OpenAI 格式（对话）。以下为常用速查：

模型后缀：-thinking 自动预算；-thinking-<数字> 精确预算（如 gemini-2.5-flash-thinking-8192）；-nothinking 关闭；gemini-3-pro-preview-thinking-low/high 直接指定级别
extra_body 配置：extra_body.google.thinking_config.thinking_budget + include_thoughts，支持特殊值：-1 自动开启、0 关闭、>0 指定预算；需 stream: true
reasoning_effort：在 -thinking 且未设置 max_tokens 时可用（low/medium/high≈20%/50%/80% 预算）
Gemini 3 Pro Preview：使用 thinking_level（LOW/HIGH，默认 HIGH），可同时结合搜索
搜索开启：推荐 OpenAI 兼容工具 "tools":[{"type":"function","function":{"name":"googleSearch"}}]；或透传 extra_body.google.tools:[{"googleSearch":{}}]
注意：需启用思考适配器（服务端配置），思考预算占用输出 token，务必使用 stream: true 才能看到 reasoning_content

示例（2.5 指定预算）：

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [
      {"role":"user","content":"给出一道中等难度的几何题并分步解析。"}
    ],
    "extra_body": {
      "google": {
        "thinking_config": { "thinking_budget": 6000, "include_thoughts": true }
      }
    },
    "stream": true
  }'

示例（3 Pro Preview 思考+搜索）：

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gemini-3-pro-preview",
    "messages": [
      {"role":"user","content":"Google 搜索一下今天广州的天气怎么样"}
    ],
    "generationConfig": {
      "thinkingConfig": { "thinkingLevel": "LOW" }
    },
    "tools": [
      { "type": "function", "function": { "name": "googleSearch" } }
    ],
    "stream": true
  }'

通义千问扩展功能

通义千问模型支持搜索、语音识别等扩展功能，所有扩展参数需放入 parameters 对象中。

搜索功能
语音识别

curl -X POST "https://api.gravitex.ai/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
    }
  }'

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "parameters": {
      "asr_options": {
        "language": "zh"
      }
    }
  }'

通义千问的所有扩展参数（如 enable_search、search_options、asr_options、temperature、top_p 等）都需要放在 parameters 对象中，而不是请求体的顶层。

联网搜索功能

部分模型支持实时联网搜索，可以获取最新信息并在响应中包含引用来源。

Claude 搜索
Grok 搜索

Claude 模型不支持通过 web_search_options 参数开启网络搜索功能，所以使用只能通过tool工具调用实现，且可能因为网络和提示词等原因不稳定,详细看上面工具调用（Functions / Tools）。基础示例（展示工具调用流程）：

curl -X POST "https://api.gravitex.ai/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.gravitex.ai/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 等
在多轮对话中，工具调用和结果会在消息历史中可见，模型可以基于之前的搜索结果继续对话

稳定性说明：

联网搜索功能依赖上游代理服务和外部搜索服务，可能存在以下不稳定性：
- 网络波动：网络连接问题可能导致搜索请求超时或失败
- 服务限制：搜索服务可能有频率限制、超时限制或临时不可用
- 搜索结果质量：某些查询可能无法找到相关信息，或搜索结果质量不佳
- 模型判断：模型会根据问题自动判断是否需要搜索，某些情况下可能不会触发搜索

Grok 模型支持通过 search_parameters 参数控制实时搜索行为。

object

搜索参数配置

mode（可选）：搜索模式，可选值：
- "off"：禁用搜索
- "auto"：模型自动判断是否需要搜索（推荐）
- "on"：强制使用搜索
return_citations（可选）：是否在响应中返回引用链接，默认为 true

基础示例：

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-4",
    "messages": [
      {"role": "user", "content": "2026年人工智能领域有什么最新进展？"}
    ],
    "search_parameters": {
      "mode": "auto"
    }
  }'

强制搜索示例：

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-4",
    "messages": [
      {"role": "user", "content": "最新的科技新闻有哪些？"}
    ],
    "search_parameters": {
      "mode": "on",
      "return_citations": true
    }
  }'

Python 示例：

from openai import OpenAI

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

completion = client.chat.completions.create(
    model="grok-4",
    messages=[
        {"role": "user", "content": "2026年人工智能领域有什么最新进展？"}
    ],
    extra_body={
        "search_parameters": {
            "mode": "auto"
        }
    }
)
print(completion.choices[0].message.content)

推荐使用 "auto" 模式，让模型自动判断是否需要搜索
搜索功能会增加响应时间，但能获取最新的实时信息
支持的模型包括 grok-4、grok-3 等系列
搜索结果会在响应中包含引用来源

GPT 文件输入（Responses API）

GPT-5 等模型支持文件输入功能，需要通过 /v1/responses 接口调用，而不是 /v1/chat/completions。

通过文件 URL 上传
通过 Base64 编码上传

您可以通过链接外部网址上传 PDF 文件：

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.gravitex.ai/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)

作为 Base64 编码的输入发送：

import base64
from openai import OpenAI

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

with open("document.pdf", "rb") as f:
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "document.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}"
                },
                {
                    "type": "input_text",
                    "text": "这份文档的主要内容是什么？"
                }
            ]
        }
    ]
)
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 字段说明。

流式响应以 SSE（Server-Sent Events）格式返回，每个分片包含部分内容：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"回"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"复"},"finish_reason":null}]}

data: [DONE]

最后一个分片通常包含 usage 统计信息。

错误处理

异常类型	触发场景	返回信息
AuthenticationError	API密钥无效或未授权	错误：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 对象中

常见问题

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

模型列表

查看所有支持的模型信息

原生 OpenAI 格式（Responses）Gemini OpenAI 格式（对话）

API 文档

对话与文本

安全与音频

图像系列

视频系列

文本补全和向量嵌入

接口模块

原生 OpenAI 格式（ChatCompletions）

简介

认证

请求参数

基础示例

高级功能

工具调用（Functions / Tools）

结构化输出（JSON Schema）

思考能力

通义千问扩展功能

联网搜索功能

GPT 文件输入（Responses API）

Grok 推理能力

usage 字段说明

通用字段

特殊场景专属字段

场景一：底层实际调用 Claude（`/v1/chat/completions` → `/v1/messages`）

场景二：底层实际调用图片生成模型（`/v1/chat/completions` → `/v1/images/generations` 语义）

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

响应格式

错误处理

支持的模型系列

OpenAI 系列

Claude 系列（Anthropic）

DeepSeek 系列

Grok 系列（xAI）

通义千问系列（Qwen）

豆包 Seed 系列（Doubao）

其他模型

注意事项

相关资源

常见问题

模型列表

​简介

​认证

​请求参数

​基础示例

​高级功能

​工具调用（Functions / Tools）

​结构化输出（JSON Schema）

​思考能力

​通义千问扩展功能

​联网搜索功能

​GPT 文件输入（Responses API）

​Grok 推理能力

​usage 字段说明

​通用字段

​特殊场景专属字段

​场景一：底层实际调用 Claude（/v1/chat/completions → /v1/messages）

​场景二：底层实际调用图片生成模型（/v1/chat/completions → /v1/images/generations 语义）

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

​响应格式

​错误处理

​支持的模型系列

​OpenAI 系列

​Claude 系列（Anthropic）

​DeepSeek 系列

​Grok 系列（xAI）

​通义千问系列（Qwen）

​豆包 Seed 系列（Doubao）

​其他模型

​注意事项

​相关资源

常见问题

模型列表

简介

认证

请求参数

基础示例

高级功能

工具调用（Functions / Tools）

结构化输出（JSON Schema）

思考能力

通义千问扩展功能

联网搜索功能

GPT 文件输入（Responses API）

Grok 推理能力

usage 字段说明

通用字段

特殊场景专属字段

场景一：底层实际调用 Claude（`/v1/chat/completions` → `/v1/messages`）

场景二：底层实际调用图片生成模型（`/v1/chat/completions` → `/v1/images/generations` 语义）

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

响应格式

错误处理

支持的模型系列

OpenAI 系列

Claude 系列（Anthropic）

DeepSeek 系列

Grok 系列（xAI）

通义千问系列（Qwen）

豆包 Seed 系列（Doubao）

其他模型

注意事项

相关资源