EasyXAI 文档
API 接入OpenAI 协议

Chat Completions

POST https://api.easyx.ai/v1/chat/completions
Authorization: Bearer easyx_ws_xxx
Content-Type: application/json

请求示例

基础文本对话

curl https://api.easyx.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "developer",
      "content": "你是一个有帮助的助手。"
    },
    {
      "role": "user",
      "content": "你好!"
    }
  ]
}'

响应示例:

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好!我能为你提供什么帮助?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default"
}

图像分析对话

curl https://api.easyx.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "这张图片里有什么?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimages_1.png"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}'

响应示例:

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "一个穿着黑色连帽衫的女孩双臂交叉站在街上,背景有店铺、南瓜装饰和几位行人。",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

函数调用

curl https://api.easyx.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "波士顿今天的天气怎么样?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "获取指定位置的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市和州,例如 San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": [
                "celsius",
                "fahrenheit"
              ]
            }
          },
          "required": [
            "location"
          ]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

响应示例:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\n\"location\": \"Boston, MA\"\n}"
            }
          }
        ]
      },
      "logprobs": null,
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99,
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

多轮对话

curl https://api.easyx.ai/v1/chat/completions \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "system",
      "content": "请用中文回答。"
    },
    {
      "role": "user",
      "content": "我叫小明。"
    },
    {
      "role": "assistant",
      "content": "你好,小明。"
    },
    {
      "role": "user",
      "content": "我叫什么名字?"
    }
  ]
}'

流式响应

curl -N https://api.easyx.ai/v1/chat/completions \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "stream": true
}'
data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

从 choices[].delta.content 读取文本片段并按顺序拼接,直到流结束。设置 stream_options.include_usage 后,支持该选项的模型还可能发送独立的 usage 数据块,此时 choices 为空数组。

回传工具结果

应用执行函数后,将原始对话、助手返回的 tool_calls 和工具结果一起发送。tool_call_id 必须与对应调用的 id 一致。function.arguments 是 JSON 字符串,执行前需解析并校验。

curl https://api.easyx.ai/v1/chat/completions \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "北京的天气怎么样?"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_weather",
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "arguments": "{\"location\": \"北京\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_weather",
      "content": "{\"temperature\": 22, \"condition\": \"晴\"}"
    }
  ]
}'

请求参数

model

  • 类型:string
  • 必填:是

要调用的模型名称,使用模型列表返回的 id。

reasoning_effort

  • 类型:string
  • 必填:否

支持推理设置的模型可以指定推理强度,可用取值随模型而不同。

messages

  • 类型:数组
  • 必需:是

到目前为止包含对话的消息列表。根据使用的模型,支持不同的消息类型(形式),如文本、图像和音频。

消息类型描述
Developer message开发者提供的指令,模型应遵循这些指令,无论用户发送什么消息。在 o1 模型及更新版本中,开发者消息取代了之前的系统消息。
System message开发者提供的指令,模型应遵循这些指令,无论用户发送什么消息。在 o1 模型及更新版本中,请使用开发者消息代替。
User message由终端用户发送的消息,包含提示或额外的上下文信息。
Assistant message模型响应用户消息发送的消息。
Tool message工具消息的内容。
Function message已弃用。

Developer message 属性:

属性类型必需描述
role字符串是消息作者的角色,此处为 developer。
content字符串或数组是开发者消息的内容。可以是文本内容(字符串)或内容部分数组。
name字符串否参与者的可选名称。为模型提供信息以区分相同角色的参与者。

System message 属性:

属性类型必需描述
role字符串是消息作者的角色,此处为 system。
content字符串或数组是系统消息的内容。可以是文本内容(字符串)或内容部分数组。
name字符串否参与者的可选名称。为模型提供信息以区分相同角色的参与者。

User message 属性:

属性类型必需描述
role字符串是消息作者的角色,此处为 user。
content字符串或数组是用户消息的内容。可以是文本内容(字符串)或内容部分数组。
name字符串否参与者的可选名称。为模型提供信息以区分相同角色的参与者。

内容部分类型:

内容部分类型描述可用于
文本内容部分文本输入。所有消息类型
图像内容部分图像输入。用户消息
音频内容部分音频输入。用户消息
文件内容部分文件输入,用于文本生成。用户消息
拒绝内容部分模型生成的拒绝消息。助手消息

文本内容部分属性:

属性类型必需描述
text字符串是文本内容。
type字符串是内容部分的类型。

图像内容部分属性:

属性类型必需描述
image_url对象是包含图像URL或base64编码的图像数据。
type字符串是内容部分的类型。

图像URL对象属性:

属性类型必需描述
url字符串是图像的URL或base64编码的图像数据。
detail字符串否指定图像的详细级别。默认为 auto。

Assistant message 属性:

属性类型必需描述
role字符串是消息作者的角色,此处为 assistant。
content字符串或数组否助手消息的内容。除非指定了 tool_calls 或 function_call,否则为必需。
name字符串否参与者的可选名称。为模型提供信息以区分相同角色的参与者。
audio对象或null否关于模型先前音频响应的数据。
function_call对象或null否已弃用,由 tool_calls 替代。应调用的函数的名称和参数,由模型生成。
tool_calls数组否模型生成的工具调用,如函数调用。
refusal字符串或null否助手的拒绝消息。

Tool message 属性:

属性类型必需描述
role字符串是消息作者的角色,此处为 tool。
content字符串或数组是工具消息的内容。
tool_call_id字符串是此消息响应的工具调用。

Function message 属性:(已弃用)

属性类型必需描述
role字符串是消息作者的角色,此处为 function。
content字符串或null是函数消息的内容。
name字符串是要调用的函数的名称。

temperature

  • 类型:数字或 null
  • 必需:否
  • 默认值:1

要使用的采样温度,介于 0 和 2 之间。较高的值(如0.8)会使输出更加随机,而较低的值(如0.2)会使其更加集中和确定性。我们通常建议更改此值或 top_p,但不要同时更改。

top_p

  • 类型:数字或 null
  • 必需:否
  • 默认值:1

一种替代采样温度的方法,称为核采样,其中模型考虑具有 top_p 概率质量的 token 结果。因此,0.1 意味着只考虑包含前 10% 概率质量的 token。

我们通常建议更改此值或 temperature,但不要同时更改。

n

  • 类型:整数或 null
  • 必需:否
  • 默认值:1

为每个输入消息生成多少个聊天补全选择。请注意,您将根据所有选择生成的 token 数量收费。保持 n 为 1 可最大限度地降低成本。

stop

  • 类型:字符串/数组/null
  • 必需:否
  • 默认值:null
  • 不支持最新的推理模型和 .o3、o4-mini

API 将停止生成更多 token 的最多 4 个序列。返回的文本不会包含停止序列。

max_tokens

  • 类型:整数或 null
  • 必需:否

聊天补全中可以生成的最大 token 数。此值可用于控制通过 API 生成的文本成本。

该值现已弃用,取而代之的是 max_completion_tokens,并且与 o1 系列模型不兼容。

max_completion_tokens

  • 类型:整数或 null
  • 必需:否

补全中可以生成的 token 数的上限,包括可见输出 token 和推理 token。

presence_penalty

  • 类型:数字或 null
  • 必需:否
  • 默认值:0

介于 -2.0 和 2.0 之间的数字。正值根据新 token 到目前为止在文本中出现的情况来惩罚它们,从而增加模型讨论新主题的可能性。

frequency_penalty

  • 类型:数字或 null
  • 必需:否
  • 默认值:0

介于 -2.0 和 2.0 之间的数字。正值根据新 token 到目前为止在文本中的现有频率来惩罚它们,从而降低模型逐字重复同一行的可能性。

logit_bias

  • 类型:map
  • 必需:否
  • 默认值:null

修改指定 token 出现在补全中的可能性。

接受一个 JSON 对象,该对象将 token(由分词器中的 token ID 指定)映射到从 -100 到 100 的关联偏差值。在数学上,偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异,但介于 -1 和 1 之间的值应该会减少或增加选择的可能性;像 -100 或 100 这样的值应该导致相关 token 被禁止或独占选择。

logprobs

  • 类型:布尔值或 null
  • 必需:否
  • 默认值:false

是否返回输出 token 的对数概率。如果为 true,则返回 message.content 中每个输出 token 的对数概率。

user

  • 类型:字符串
  • 必需:否

表示最终用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。了解更多。

stream_options

  • 类型:对象或 null
  • 必需:否
  • 默认值:null

流式响应的选项。仅在设置 stream: true 时使用。

可能的属性:

属性类型必需描述
include_usage布尔值否如果设置,将在 data: [DONE] 消息之前流式传输一个附加块。该块上的 usage 字段显示整个请求的 token 使用统计信息,choices 字段始终为空数组。所有其他块也将包含 usage 字段,但值为 null。注意:如果流被中断,您可能不会收到包含请求总 token 使用量的最终使用块。

response_format

  • 类型:对象
  • 必需:否

指定模型必须输出的格式。

  • 设置为 { "type": "json_schema", "json_schema": {...} } 启用结构化输出,确保模型将匹配您提供的 JSON schema。
  • 设置为 { "type": "json_object" } 启用 JSON 模式,确保模型生成的消息是有效的 JSON。

重要提示:使用 JSON 模式时,您还必须通过系统或用户消息自行指示模型生成 JSON。否则,模型可能会生成无尽的空白直到生成达到 token 限制。

可能的类型:

类型描述
text默认响应格式。用于生成文本响应。
json_schemaJSON Schema 响应格式。用于生成结构化 JSON 响应。了解更多关于结构化输出的信息。
json_objectJSON 对象响应格式。一种较老的生成 JSON 响应的方法。对于支持的模型,推荐使用 json_schema。

text 属性:

属性类型必需描述
type字符串是正在定义的响应格式类型。始终为 text。

json_schema 属性:

属性类型必需描述
json_schema对象是结构化输出配置选项,包括 JSON Schema。
type字符串是正在定义的响应格式类型。始终为 json_schema。

json_schema.json_schema 属性:

属性类型必需描述
name字符串是响应格式的名称。必须是 a-z、A-Z、0-9 或包含下划线和破折号,最大长度为 64。
description字符串否响应格式的用途描述,模型用它来确定如何以该格式响应。
schema对象否响应格式的架构,描述为 JSON Schema 对象。
strict布尔值或 null否是否在生成输出时启用严格架构遵守。如果设置为 true,模型将始终遵循 schema 字段中定义的确切架构。strict 为 true 时,仅支持 JSON Schema 的子集。

json_object 属性:

属性类型必需描述
type字符串是正在定义的响应格式类型。始终为 json_object。

tools

  • 类型:数组
  • 必需:否

模型可能调用的工具列表。目前仅支持函数作为工具。使用此参数提供模型可能生成 JSON 输入的函数列表。最多支持 128 个函数。

属性:

属性类型必需描述
function对象是要调用的函数信息
type字符串是工具的类型。目前,仅支持 function。

function 属性:

属性类型必需描述
name字符串是要调用的函数名称。必须是a-z、A-Z、0-9,或包含下划线和破折号,最大长度为64。
description字符串否函数功能的描述,模型用它来选择何时以及如何调用函数。
parameters对象否函数接受的参数,描述为JSON Schema对象。请参阅指南获取示例,以及JSON Schema参考了解格式文档。省略parameters定义一个空参数列表的函数。
strict布尔值或 null否默认值:false。是否在生成函数调用时启用严格架构遵守。如果设置为 true,模型将遵循 parameters 字段中定义的确切架构。strict 为 true 时,仅支持 JSON Schema 的子集。详情请参阅函数调用指南中的结构化输出部分。

tool_choice

  • 类型:字符串或对象
  • 必需:否

控制模型调用哪个工具(如果有):

  • none:模型不会调用任何工具,而是生成消息
  • auto:模型可以在生成消息或调用一个或多个工具之间选择
  • required:模型必须调用一个或多个工具
  • {"type": "function", "function": {"name": "my_function"}}:强制模型调用特定工具

当没有工具时默认为 none,有工具时默认为 auto。

可能的类型:

类型描述
字符串none 表示模型不会调用任何工具,而是生成消息。auto 表示模型可以在生成消息或调用一个或多个工具之间选择。required 表示模型必须调用一个或多个工具。
对象指定模型应使用的工具。用于强制模型调用特定函数。

对象属性:

属性类型必需描述
function对象是包含函数信息的对象
type字符串是工具的类型。目前,仅支持 function。

function 属性:

属性类型必需描述
name字符串是要调用的函数名称。

parallel_tool_calls

  • 类型:布尔值
  • 必需:否
  • 默认值:true

是否在工具使用期间启用并行函数调用。

stream

  • 类型:布尔值或 null
  • 必需:否
  • 默认值:false

如果设置为 true,模型响应数据将在生成时通过服务器发送事件流式传输到客户端。请参阅下方的流式响应部分获取更多信息,以及流式响应指南了解如何处理流式事件。

top_logprobs

  • 类型:整数或 null
  • 必需:否

0 到 20 之间的整数,指定在每个 token 位置返回的最可能 token 的数量,每个 token 都有关联的对数概率。如果使用此参数,必须将 logprobs 设置为 true。

响应字段

聊天补全对象

返回一个聊天补全对象,如果请求被流式传输,则返回聊天补全块对象的流式序列。

id

  • 类型:字符串
  • 说明:响应的唯一标识符

object

  • 类型:字符串
  • 说明:对象类型,值为 "chat.completion"

created

  • 类型:整数
  • 说明:响应创建时间戳

model

  • 类型:字符串
  • 说明:使用的模型名称

system_fingerprint

  • 类型:字符串
  • 说明:系统指纹标识符,表示模型运行的后端配置。可以与seed请求参数一起使用,以了解何时进行了可能影响确定性的后端更改。

choices

  • 类型:数组
  • 说明:包含生成的回复选项列表。如果 n 大于 1,则可以有多个选项。
  • 属性:
    • index: 选项在选项列表中的索引。
    • message: 模型生成的聊天补全消息。
      • role: 消息作者的角色。
      • content: 消息的内容,可能为 null。
      • refusal: 模型生成的拒绝消息,可能为 null。
      • annotations: 消息的注释,在适用时提供,例如使用网络搜索工具时。
        • type: 注释类型,URL引用时始终为 "url_citation"。
        • url_citation: 使用网络搜索时的URL引用。
          • start_index: URL引用在消息中的第一个字符的索引。
          • end_index: URL引用在消息中的最后一个字符的索引。
          • url: 网络资源的URL。
          • title: 网络资源的标题。
      • audio: 如果请求了音频输出模态,此对象包含来自模型的音频响应的数据。
        • data: 模型生成的Base64编码音频字节,格式在请求中指定。
        • id: 此音频响应的唯一标识符。
        • transcript: 模型生成的音频的转录。
        • expires_at: 此音频响应在服务器上可用于多轮对话的Unix时间戳(秒)。
      • function_call: (已弃用)应调用的函数的名称和参数,由模型生成。已被 tool_calls 替代。
        • name: 要调用的函数的名称。
        • arguments: 用于调用函数的参数,由模型以JSON格式生成。
      • tool_calls: 模型生成的工具调用,如函数调用。
        • id: 工具调用的ID。
        • type: 工具的类型。目前,仅支持 function。
        • function: 模型调用的函数。
          • name: 要调用的函数的名称。
          • arguments: 用于调用函数的参数,由模型以JSON格式生成。注意,模型并不总是生成有效的JSON,并且可能会产生您函数架构中未定义的参数。在调用函数之前,请在代码中验证参数。
    • logprobs: 对数概率信息。
      • content: 带有对数概率信息的消息内容 token 列表。
        • token: token。
        • logprob: 此 token 的对数概率,如果它在前20个最可能的 token 内。否则,使用-9999.0的值表示此 token 非常不可能。
        • bytes: 表示 token 的UTF-8字节表示的整数列表。在字符由多个 token 表示且必须组合它们的字节表示以生成正确的文本表示的情况下很有用。如果 token 没有字节表示,则可能为null。
        • top_logprobs: 在此 token 位置上最可能的 token 及其对数概率的列表。在罕见情况下,返回的top_logprobs数量可能少于请求的数量。
      • refusal: 带有对数概率信息的消息拒绝 token 列表。
    • finish_reason: 模型停止生成 token 的原因。如果模型到达自然停止点或提供的停止序列,则为 "stop";如果达到请求中指定的最大 token 数,则为 "length";如果由于内容过滤器标记而省略内容,则为 "content_filter";如果模型调用了工具,则为 "tool_calls";如果模型调用了函数,则为 "function_call"(已弃用)。

usage

  • 类型:对象
  • 说明:补全请求的使用统计信息。
  • 属性:
    • prompt_tokens: 提示中的 token 数。
    • completion_tokens: 生成的补全中的 token 数。
    • total_tokens: 请求中使用的 token 总数(提示 + 补全)。
    • prompt_tokens_details: 提示中使用的 token 的细分。
      • cached_tokens: 提示中存在的缓存 token。
      • audio_tokens: 提示中存在的音频输入 token。
    • completion_tokens_details: 补全中使用的 token 的细分。
      • reasoning_tokens: 模型生成的推理 token。
      • audio_tokens: 模型生成的音频 token。
      • accepted_prediction_tokens: 使用预测输出时,预测中出现在补全中的 token 数。
      • rejected_prediction_tokens: 使用预测输出时,预测中未出现在补全中的 token 数。但是,与推理 token 一样,这些 token 仍计入计费、输出和上下文窗口限制的总补全 token 中。

service_tier

Python SDK

pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="easyx_ws_xxx",
    base_url="https://api.easyx.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

Node.js SDK

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "easyx_ws_xxx",
  baseURL: "https://api.easyx.ai/v1",
});

const stream = await client.chat.completions.create({
  model: "gpt-4.1",
  messages: [{ role: "user", content: "Hello" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

OpenAI Chat Completions reference