EasyXAI 文档
API 接入OpenAI 协议

Responses

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

请求参数

参数类型必填说明
modelstring是模型名称。
inputstring / array是文本、消息数组或输入项;内容块使用 input_text、input_image 等类型。
instructionsstring否系统或开发者指令。
max_output_tokensinteger否输出 token 上限,包含推理 token。
streamboolean否true 表示接收 SSE 事件流。
temperature / top_pnumber否采样参数,适用范围随模型而不同。
reasoningobject否支持推理的模型可设置 effort、summary 等选项。
textobject否输出格式;text.format.type 可设为 text、json_object 或 json_schema。
toolsarray否函数定义;name、parameters、description 直接放在 function 工具对象上。
tool_choicestring / object否auto、none、required,或指定函数的对象。
parallel_tool_callsboolean否是否允许一次响应包含多个函数调用。
truncationstring否上下文截断策略,auto 或 disabled。
includearray否要求支持该选项的模型返回额外数据。
metadataobject否附加的键值元数据。

请求示例

基础文本响应

curl https://api.easyx.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "input": "讲一个三句话的关于独角兽的睡前故事。"
}'

响应示例:

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "在一个宁静的月夜下,一只名叫璐米娜的独角兽发现了一个倒映着星星的隐藏水池。当她将独角浸入水中时,水池开始闪烁,显现出通往一个有着无尽夜空的魔法世界的路径。充满好奇,璐米娜为所有做梦的人许下愿望,希望他们能找到自己的隐藏魔法,当她回头望去,她的蹄印像星尘一样闪烁。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 36,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 87,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 123
  },
  "user": null,
  "metadata": {}
}

图像分析响应

curl https://api.easyx.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "描述这张图片中的内容"
        },
        {
          "type": "input_image",
          "image_url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imageToimages_1.png"
        }
      ]
    }
  ]
}'

响应示例:

{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "created_at": 1741476777,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "一个穿着黑色连帽衫的女孩双臂交叉站在街上,背景有店铺、南瓜装饰和几位行人。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "user": null,
  "metadata": {}
}

函数调用

curl https://api.easyx.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -d '{
  "model": "gpt-4.1",
  "input": "波士顿今天的天气如何?",
  "tools": [
    {
      "type": "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",
          "unit"
        ]
      }
    }
  ],
  "tool_choice": "auto"
}'

响应示例:

{
  "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
  "object": "response",
  "created_at": 1741294021,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1",
  "output": [
    {
      "type": "function_call",
      "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
      "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
      "name": "get_current_weather",
      "arguments": "{\"location\":\"波士顿, MA\",\"unit\":\"celsius\"}",
      "status": "completed"
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "description": "获取指定位置的当前天气",
      "name": "get_current_weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "城市和州,例如 San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": [
              "celsius",
              "fahrenheit"
            ]
          }
        },
        "required": [
          "location",
          "unit"
        ]
      },
      "strict": true
    }
  ],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 291,
    "output_tokens": 23,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 314
  },
  "user": null,
  "metadata": {}
}

多轮对话

每次请求通过 input 发送对话历史。当前不支持 previous_response_id 和 conversation。

curl https://api.easyx.ai/v1/responses \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "input": [
    {
      "role": "user",
      "content": "我叫小明。"
    },
    {
      "role": "assistant",
      "content": "你好,小明。"
    },
    {
      "role": "user",
      "content": "我叫什么名字?"
    }
  ]
}'

流式响应

curl -N https://api.easyx.ai/v1/responses \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "input": "Hello",
  "stream": true
}'
event: response.created
data: {"type":"response.created","response":{"id":"resp_example","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Hello"}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Hello"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","status":"completed"}}

读取 response.output_text.delta 中的 delta 拼接文本,同时处理 response.completed、response.incomplete、response.failed 和 error。示例展示文本处理所需的事件字段,实际事件还可能包含其他字段。

回传函数结果

应用执行函数后,将返回的 function_call 项和 function_call_output 项追加到原始 input 中。两者的 call_id 必须一致。

curl https://api.easyx.ai/v1/responses \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "input": [
    {
      "role": "user",
      "content": "北京的天气怎么样?"
    },
    {
      "type": "function_call",
      "call_id": "call_weather",
      "name": "get_current_weather",
      "arguments": "{\"location\": \"北京\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_weather",
      "output": "{\"temperature\": 22, \"condition\": \"晴\"}"
    }
  ]
}'

结构化输出

curl https://api.easyx.ai/v1/responses \
  -H "Authorization: Bearer easyx_ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-4.1",
  "input": "提取姓名:我叫小明。",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  }
}'

响应字段

原始 HTTP 响应需遍历 output 中 type 为 message 的项,再读取 content 中 type 为 output_text 的 text。SDK 的 output_text 是便捷属性,不是原始 HTTP 响应必有的顶层字段。

成功响应

返回一个响应对象,如果请求被流式传输,则返回响应对象的流式序列。

id

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

object

  • 类型:字符串
  • 说明:对象类型,值为 "response"

created_at

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

status

  • 类型:字符串
  • 说明:响应状态,如 "completed"、"in_progress" 等

error

  • 类型:对象或null
  • 说明:如果发生错误,包含错误信息

incomplete_details

  • 类型:对象或null
  • 说明:如果响应不完整,包含详细信息

instructions

  • 类型:字符串或null
  • 说明:提供给模型的系统指令

max_output_tokens

  • 类型:整数或null
  • 说明:最大输出标记数

model

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

output

  • 类型:数组
  • 说明:包含生成的回复和工具调用
  • 可能包含:
    • 消息对象(type: "message")
    • 工具使用对象(type: "tool_use")

parallel_tool_calls

  • 类型:布尔值
  • 说明:是否启用并行工具调用

reasoning

  • 类型:对象
  • 说明:推理相关信息

usage

  • 类型:对象
  • 说明:token 使用统计
  • 属性:
    • input_tokens: 输入使用的 token 数
    • input_tokens_details: 输入 token 详细信息
    • output_tokens: 输出使用的 token 数
    • output_tokens_details: 输出 token 详细信息
    • total_tokens: 总 token 数

user

  • 类型:字符串或null
  • 说明:用户标识符

metadata

  • 类型:对象
  • 说明:附加的元数据信息

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.responses.create(model="gpt-4.1", input="Hello")
print(response.output_text)

stream = client.responses.create(model="gpt-4.1", input="Hello", stream=True)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

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 response = await client.responses.create({
  model: "gpt-4.1",
  input: "Hello",
});
console.log(response.output_text);

OpenAI Responses reference