Chat Aggregation

Authentication

参考接入 BytePower

请求参数 Response Format 控制结构化输出说明

response_format 参数用于控制 AI 模型的响应格式，支持结构化 JSON 输出。

平台支持差异

OpenAI：原生支持结构化输出（response_format.json_schema），GPT-4o 及之后的模型支持
Gemini：通过 OpenAI 兼容接口支持，使用相同的实现方式，Gemini 2.0 及后续的模型支持
Claude：暂不支持原生结构化输出，需要通过 Prompt Engineering 或 Tools 方式实现

支持的格式类型

1. 简单 JSON 对象模式（保持向后兼容）

支持两种写法：

写法一（字符串格式）：

json

{
  "response_format": "json_object"
}

写法二（对象格式）：

json

{
  "response_format": {
    "type": "json_object"
  }
}

2. 结构化输出模式（新功能）

使用 JSON Schema 定义精确的输出结构：

json

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "schema_name",
      "description": "Schema description",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          // 定义属性
        },
        "required": ["field1", "field2"],
        "additionalProperties": false
      }
    }
  }
}

Chat Aggregation

接口功能： chat aggregation

聚合多个 AI 模型，一个模型出现错误可自动切换下一个

Method & Path

POST {domain}/bp/ai/chat/aggregation
POST {domain}/bp/server/user/{user_id}/ai/chat/aggregation

Request

content-type: "application/json"

Parameters	Type	Required	Desc
strategies	[]string	true	strategy 列表
chat_id	string	false	server save history
messages	object	true	聊天内容
tools	[]object	false	完整的 Schema 定义请参考： OpenAI - Function calling - Defining functions
parameters	object	false	用于渲染服务端配置的 system prompt 中的变量
response_format	object	false	控制 AI 模型的响应格式，详细见上面的说明

System Prompt 的优先级和处理规则如下：

消息优先级：如果 messages 参数中包含 role 为 system 的消息，则优先使用该消息作为 System Prompt
配置兜底：如果 messages 中无 system 消息，则按以下规则处理：
- 当 BytePower Console 中 "System Prompt" 的 enabled 为 true 时，使用 Console 中配置的 prompt_name，并通过 parameters 进行模板渲染
- 当 enabled 为 false 时，不使用任何 System Prompt

OpenAI 工具调用相关文档：
OpenAI - Create chat completion - Functions
OpenAI - Handling function calls

Claude 兼容 OpenAI 工具调用相关文档：
Claude - OpenAI SDK compatibility

Gemini 兼容 OpenAI 工具调用相关文档：
Gemini - OpenAI compatibility - Function calling

⚠️ 注意️ ⚠️：

Gemini 工具调用目前在稳定性表现上与 OpenAI 存在一定差距，
为确保业务稳定运行，建议在生产使用前进行充分的场景测试和风险评估

请求示例

基础请求示例：

json

{
  "chat_id": "",
  "strategies": ["conversation_aws_gemini_aws", "conversation_aws_claude_aws", "conversation_aws_openai_aws"],
  "messages": [
    {
      "content": "hi",
      "role": "user"
    }
  ],
  "parameters": {
    "UserName": "Lily"
  }
}

结构化输出请求示例（参考上述 Response Format 结构化输出部分）：

json

{
  "strategies": ["openai_gpt4"],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "contact_extraction",
      "description": "Extract contact information from text",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Contact name"
          },
          "phone": {
            "type": "string",
            "description": "Phone number"
          },
          "email": {
            "type": "string",
            "description": "Email address"
          }
        },
        "required": ["name", "phone", "email"],
        "additionalProperties": false
      }
    }
  },
  "messages": [
    {
      "role": "user",
      "content": "提取联系人信息: 张三, 电话 13800138000, 邮箱 zhangsan@example.com"
    }
  ]
}

工具调用请求示例：

json

{
  "strategies": ["openai-thinking"],
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "北京天气怎么样？"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current temperature for a given location.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City and country e.g. Bogotá, Colombia"
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "parameters": {
    "UserName": "Lily"
  }
}

Response

HTTP 状态码：200

json

{
  "asset": [
    {
      "name": "ai_free_asset",
      "quantity": 942,
      "recoverable": false,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "name": "tt",
      "quantity": 3,
      "recoverable": false,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "bp_product_id": "BUY4MF6V5ZJGXXJ3",
      "custom_expire_time": "0001-01-01T00:00:00Z",
      "expire_time": "2024-11-23T06:41:25Z",
      "is_auto_renewable": false,
      "is_consumable": true,
      "is_refund": false,
      "is_trial_period": false,
      "last_recovery_time": "2025-02-22T01:06:34Z",
      "name": "ai_vip_asset",
      "origin": "purchase",
      "platform": "stripe",
      "product_id": "prod_R4lGIYYAij8OBZ",
      "quantity": 0,
      "receipt_id": "sub_1QCbmTDESvfLoR1GbdjJ6F6I",
      "recoverable": true,
      "refund_time": "0001-01-01T00:00:00Z",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 0,
      "type": "subscription",
      "valid_seconds": 0
    },
    {
      "bp_product_id": "",
      "custom_expire_time": "2025-03-08T09:25:12.484303Z",
      "expire_time": "0001-01-01T00:00:00Z",
      "is_auto_renewable": false,
      "is_consumable": true,
      "is_refund": false,
      "is_trial_period": false,
      "name": "vip",
      "origin": "purchase",
      "platform": "",
      "product_id": "",
      "quantity": 1000,
      "receipt_id": "",
      "refund_time": "0001-01-01T00:00:00Z",
      "sub_canceled": false,
      "sub_canceled_time": "0001-01-01T00:00:00Z",
      "sub_canceled_ts": 0,
      "total_quantity": 1000,
      "type": "subscription",
      "valid_seconds": 0
    }
  ],
  "chat_id": "",
  "current_count": 7,
  "current_total_count": 7,
  "data": {
    "id": "",
    "object": "chat.completion",
    "created": 1742979219,
    "model": "gemini-1.5-flash-latest",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hi there! How can I help you today?\n"
        },
        "finish_reason": "stop",
        "content_filter_results": {
          "hate": {
            "filtered": false
          },
          "self_harm": {
            "filtered": false
          },
          "sexual": {
            "filtered": false
          },
          "violence": {
            "filtered": false
          },
          "jailbreak": {
            "filtered": false,
            "detected": false
          },
          "profanity": {
            "filtered": false,
            "detected": false
          }
        }
      }
    ],
    "usage": {
      "prompt_tokens": 1,
      "completion_tokens": 11,
      "total_tokens": 12,
      "prompt_tokens_details": null,
      "completion_tokens_details": null
    },
    "system_fingerprint": ""
  },
  "unit_price": {
    "input_per_price": 0,
    "output_per_price": 0,
    "output_token": 70,
    "input_token": 415
  },
  "strategy": "conversation_aws_gemini_aws"
}

工具调用 HTTP 状态码：200

json

{
  "asset": [
    {
      "name": "ai_free_asset",
      "quantity": 40,
      "recoverable": false,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "name": "ai_intruction_test",
      "quantity": 3,
      "recoverable": false,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "name": "ai_intruction_test_1",
      "quantity": 2,
      "recoverable": false,
      "type": "consumable",
      "valid_seconds": 0
    },
    {
      "last_recovery_time": "2025-07-21T00:00:00Z",
      "name": "test_tmpe",
      "quantity": 4,
      "recoverable": true,
      "type": "consumable",
      "valid_seconds": 0
    }
  ],
  "chat_id": "CtFREJAHGKNYNN5AFT",
  "current_count": 5,
  "current_total_count": 5,
  "data": {
    "id": "chatcmpl-BvfvYRjt7F4qRShhaGMLxhE16dXqz",
    "object": "chat.completion",
    "created": 1753085564,
    "model": "gpt-4o-mini-2024-07-18",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "tool_calls": [
            {
              "id": "call_4xG2q9CMd3O4fVPiAwIv8fz5",
              "type": "function",
              "function": {
                "name": "get_weather",
                "arguments": "{\"location\":\"北京, 中国\"}"
              }
            }
          ]
        },
        "finish_reason": "tool_calls",
        "content_filter_results": {
          "hate": {
            "filtered": false
          },
          "self_harm": {
            "filtered": false
          },
          "sexual": {
            "filtered": false
          },
          "violence": {
            "filtered": false
          },
          "jailbreak": {
            "filtered": false,
            "detected": false
          },
          "profanity": {
            "filtered": false,
            "detected": false
          }
        }
      }
    ],
    "usage": {
      "prompt_tokens": 64,
      "completion_tokens": 16,
      "total_tokens": 80,
      "prompt_tokens_details": {
        "audio_tokens": 0,
        "cached_tokens": 0
      },
      "completion_tokens_details": {
        "audio_tokens": 0,
        "reasoning_tokens": 0,
        "accepted_prediction_tokens": 0,
        "rejected_prediction_tokens": 0
      }
    },
    "system_fingerprint": ""
  },
  "unit_price": {
    "input_per_price": 0,
    "output_per_price": 0,
    "output_token": 70,
    "input_token": 415
  },
  "strategy": "openai-thinking"
}

结构化输出 HTTP 状态码：200

json

{
  "asset": [
    {
      "last_recovery_time": "2025-10-28T00:00:00Z",
      "name": "test_tmpe",
      "quantity": 4,
      "recoverable": true,
      "type": "consumable",
      "valid_seconds": 0
    }
  ],
  "chat_id": "",
  "current_count": 1,
  "current_total_count": 9,
  "data": {
    "id": "chatcmpl-CVaccDOySEAzsW3GK8lUamSU93T2g",
    "object": "chat.completion",
    "created": 1761644978,
    "model": "gpt-4o-2024-08-06",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "{\"email\":\"zhangsan@example.com\",\"name\":\"张三\",\"phone\":\"13800138000\"}"
        },
        "finish_reason": "stop",
        "content_filter_results": {
          "hate": {
            "filtered": false
          },
          "self_harm": {
            "filtered": false
          },
          "sexual": {
            "filtered": false
          },
          "violence": {
            "filtered": false
          },
          "jailbreak": {
            "filtered": false,
            "detected": false
          },
          "profanity": {
            "filtered": false,
            "detected": false
          }
        }
      }
    ],
    "usage": {
      "prompt_tokens": 101,
      "completion_tokens": 21,
      "total_tokens": 122,
      "prompt_tokens_details": {
        "audio_tokens": 0,
        "cached_tokens": 0
      },
      "completion_tokens_details": {
        "audio_tokens": 0,
        "reasoning_tokens": 0,
        "accepted_prediction_tokens": 0,
        "rejected_prediction_tokens": 0
      }
    },
    "system_fingerprint": "fp_65564d8ba5"
  },
  "strategy": "openai",
  "unit_price": {
    "input_per_price": 8,
    "output_per_price": 10,
    "output_token": 21,
    "input_token": 101
  }
}

Chat Aggregation Stream

接口功能： chat aggregation stream

聚合多个 AI 模型，一个模型出现错误可自动切换下一个但如果已经处于流式返回结果中，则不会切换

Method & Path

POST {domain}/bp/ai/chat/aggregation/stream
POST {domain}/bp/server/user/{user_id}/ai/chat/aggregation/stream

Request

content-type: "application/json"

请求参数与 Chat Aggregation 相同，同样支持 response_format 参数用于结构化输出。

平台支持和使用方式请参考 Response Format 结构化输出部分。

基础流式请求示例：

json

{
  "chat_id": "",
  "strategies": ["conversation_aws_gemini_aws", "conversation_aws_claude_aws", "conversation_aws_openai_aws"],
  "messages": [
    {
      "content": "hi",
      "role": "user"
    }
  ],
  "parameters": {
    "message": "what's your name?"
  }
}

带结构化输出的流式请求示例：

json

{
  "strategies": ["openai_gpt4"],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "user_info",
      "description": "Extract user information",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "greeting": {
            "type": "string",
            "description": "Greeting message"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of assistant capabilities"
          }
        },
        "required": ["greeting", "capabilities"],
        "additionalProperties": false
      }
    }
  },
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下你的功能"
    }
  ]
}

Response

HTTP 状态码：200

json

event: start
data: {"content":"start","timestamp":1742981254117}

event: assistant_output_chunk
data: {"content":"Hi","timestamp":1742981269242}

event: assistant_output_chunk
data: {"content":" there! How can I help you today?\n","timestamp":1742981269368}

event: chat
data: {"content":{"chat_id":"","strategy":"conversation_aws_gemini_aws","unit_price":{"input_per_price":0,"output_per_price":0,"output_token":106,"input_token":21}},"timestamp":1742981269384}

event: end
data: {"content":"end","timestamp":1742981269384}

Instruction Aggregation

接口功能： instruction aggregation

聚合多个 AI 模型，一个模型出现错误可自动切换下一个

预设 Prompt 的单次问答的与 AI 交互的方式。通过配置一组固定的 Prompt 实现一个具体功能的提问模板，请求服务端时只需要将关键的信息通过参数传递。

Method & Path

POST {domain}/bp/ai/chat/aggregation/instruction
POST {domain}/bp/server/user/{user_id}/ai/chat/aggregation/instruction

Request

Headers
Content-Type: application/json
Body
Parameters Type Required Desc
strategies []string true instruction name 列表
parameters object false 用于渲染服务端配置的 prompt 中的变量，包含 system, user

Parameters	Type	Required	Desc
`strategies`	`[]string`	`true`	instruction name 列表
`parameters`	`object`	`false`	用于渲染服务端配置的 prompt 中的变量，包含 system, user

json

{
  "strategies": ["openai4o", "claude3.7"],
  "parameters": {
    "message": "what's your name?"
  }
}

Response

HTTP 状态码：200

json

{
  "instruction": {
    "content": "I’m called ChatGPT. How can I assist you today?"
  },
  "unit_price": {
    "input_per_price": 0,
    "output_per_price": 0
  },
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 14,
    "total_tokens": 26,
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "audio_tokens": 0,
      "reasoning_tokens": 0
    }
  }
}

Chat Aggregation ​

Authentication ​

请求参数 Response Format 控制结构化输出说明 ​

平台支持差异 ​

支持的格式类型 ​

1. 简单 JSON 对象模式（保持向后兼容） ​

2. 结构化输出模式（新功能） ​

Chat Aggregation ​

Method & Path ​

Request ​

请求示例 ​

Response ​

Chat Aggregation Stream ​

Method & Path ​

Request ​

Response ​

Instruction Aggregation ​

Method & Path ​

Request ​

Response ​

Chat Aggregation

Authentication

请求参数 Response Format 控制结构化输出说明

平台支持差异

支持的格式类型

1. 简单 JSON 对象模式（保持向后兼容）

2. 结构化输出模式（新功能）

Chat Aggregation

Method & Path

Request

请求示例

Response

Chat Aggregation Stream

Method & Path

Request

Response

Instruction Aggregation

Method & Path

Request

Response