API接入协议

API接入参数说明

请求体 请求体为 JSON 格式，字段需遵循OpenAI大模型调用规范，参考以下定义

{ 
  "conversation_id": "123", //必填, 会话id用于区别不同的会话
  "agent": "default",  //选填, agent标识默认default
  "messages": [  //必填, 对话数组
    {
      "role": "system", //选填, 角色
      "content": "你是一个专业的代码助手" //必填, 对话内容支持markdown
    },
    {
      "role": "user",                    
      "content": "请帮我写一个Python函数，计算两个数的和。"
    }
  ],
  "context": {   //选填, 会话级别的上下文
        "k1": "v1",
        "k2": "v2"                      
    }
}

请求参数说明

字段名	类型	示例值	是否必填	说明
conversation_id	string	"123"	必填	会话id, 用于隔离不同的对话
messages	array	[ {...} ]	必填	对话历史数组，包含 role 和 content
messages.role	string	"system"	选填	• system：设定模型行为 • user：用户输入 • assistant：模型回复
messages.content	string	"hello"	必填	对话内容，支持markdown格式渲染
context	kv		可选	上下文的变量和值

响应体

{
  "conversation_id": "1234", // 必填, 会话id用于区别不同的会话
  "object": "chat.completion.chunk",     //必填, 响应类型（固定为"chat.completion.chunk"）
  "created": 1724828377,                 //选填, 生成消息时间戳（秒）
  "agent": "default",              // 选填, agent标识, 默认default
  "context": {   //选填, 会话级别的上下文
        "k1": "v1",
        "k2": "v2"                      
    },
  "choices": [                           //必填,增量输出的流式消息
    {
      "index": 0,                        //选填, 增量消息的序号
      "delta": {                         //必填, 增量消息
        "content": "    return a + b\n"  //必填, 增量消息内容
        "role": "summary",               //选填, 角色
        "tool_calls":[                   //选填, 
           {
            "id": "call_abc123",          //必填, 工具调用的唯一标识（由模型生成）
            "type": "function",           //必填, 调用类型（固定为"function"）
            "function": {
              "name": "get_weather",      //选填, 工具/函数名称
              "arguments": "{\"location\": \"北京\", \"date\": \"2023-10-06\"}"  //选填, 工具所需的参数（JSON格式）
           }
         }
       ]             
      },
      "finish_reason": "stop"            //选填, 结束原因
    }
  ]
}

流式响应参数说明

字段名	类型	示例值	是否必填	说明
conversation_id	string	"1234"	必填	会话id
object	string	"chat.completion.chunk"	必填	响应对象类型，固定为 "chat.completion.chunk"
created	integer	1724828377	选填	Unix 时间戳（秒）。
agent	string	"helloworld"	选填	智能体标识
choices	array	[ {...} ]	必填	候选输出数组。
context	kv		选填	可选上下文的变量和值

Choice 对象字段

字段名	类型	示例值	是否必填	说明
delta	object	{ "content": " return a + b\n" }	必填	增量内容，仅在流式响应时返回。
delta.content	string	" return a + b\n"	必填	增量的消息内容
delta.role	string	"summary"	选填	• system：设定模型行为 • user：用户输入 • assistant：模型回复
delta.tool_call	object	{}	选填	调用工具信息
finish_reason	string	"stop"	选填	结束原因： • "stop"：正常结束 • "length"：达到 max_tokens 限制 • "content_filter"：内容被过滤 • null：尚未结束

Tool_call 对象字段

字段名	类型	示例值	是否必填	说明
id	string	"123"	必填	工具调用的唯一标识
type	string	"function"	必填	调用类型（固定为"function"）
function	object	"{\"name\":\"get_weather\", \"arguments\":\"123\"}"	必填	调用工具的信息
function.name	string	"get_weather"	选填	调用工具名
function.arguments	string	"{\"location\":\"北京\",\"date\":\"2025-10-06\"}"	选填	调用工具参数，如果是复杂json需要转义

注意事项

服务的稳定性

• 需要尽量保障你的服务可用性(SLA)高于99.9%。
• 可根据需要进行限流设置，避免流量突增导致服务不可用。
• 需要尽量保障首字响应在5秒内, 流式响应token速率不低于10 token/s。

错误处理​

1. 检查 HTTP 状态码 常见状态码及含义如下：

状态码	含义
200	请求成功
401	未授权（API Key 错误）
429	速率限制（超过调用次数限制）
500	服务器内部错误

2. 解析响应中的 error 字段 如果返回体中包含 error 字段，可获取具体错误信息。例如：

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error"
  }
}