模型体验

体验请求使用 x-keystone-token: 通过控制面鉴权，并通过 X-Experience-Key 提供网关 API Key。X-Experience-Host 选择网关路由域名。

chat / images / speech / transcriptions 请求体原样转发，Beacon 不定义统一固定的上游字段表。请求体最大 32 MiB。支持字段与效果取决于所选后端服务。

上游状态 >= 400 时，Beacon 返回 HTTP 200 并保留错误 JSON；真实上游状态在 X-Upstream-Status 中。非 JSON 上游错误会包装为 error 对象。

chat 可返回 SSE；speech 返回音频二进制；transcriptions 使用 multipart/form-data。音色、语言等能力由 audio/capabilities 查询。

方法	路径（产品接口统一前缀 /api/v1）	功能
POST	/experience/chat	流式聊天补全
POST	/experience/images	生成图片
POST	/experience/audio/speech	生成语音
GET	/experience/audio/capabilities	查询语音模型能力
POST	/experience/audio/transcriptions	音频转写
GET	/experience/routes	查询体验中心可用路由

对话

功能介绍

模型对话。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/experience/chat

接口请求头

请求头	说明
X-Experience-Host	路由域名。
X-Experience-Key	必选，网关 API Key。

请求消息

请求体由 Beacon 原样转发给后端服务，字段约束以所选服务为准；以下为常见调用格式，非 Beacon 本地校验规则。

字段	类型	说明
model	string	路由提供的模型名称
messages	array	对话消息数组，如 role/content
stream	boolean	是否请求 SSE

响应消息

成功体沿用上游：chat 为 JSON 或 text/event-stream；images 为 JSON；speech 为音频字节；transcriptions 为上游转写结果。具体取决于当前接口与请求参数。上游错误见调用方式。

请求示例

POST https://{endpoint}/api/v1/experience/chat
x-keystone-token: <Keystone Token>
X-Experience-Key: <API_KEY>
X-Experience-Host: demo.ai.example.com
Content-Type: application/json

{
  "model": "demo-model",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "stream": true
}

正常响应示例

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"choices":[{"delta":{"content":"你好"}}]}

data: [DONE]

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

本地可能返回 400、413、500、502、503；上游 >=400 被包装为 200，请检查 X-Upstream-Status 与 error。

生成图片

功能介绍

生成图片。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/experience/images

接口请求头

请求头	说明
X-Experience-Host	路由域名。
X-Experience-Key	必选，网关 API Key。

请求消息

请求体由 Beacon 原样转发给后端服务，字段约束以所选服务为准；以下为常见调用格式，非 Beacon 本地校验规则。

字段	类型	说明
model	string	路由提供的模型名称
prompt	string	图像描述

响应消息

请求示例

POST https://{endpoint}/api/v1/experience/images
x-keystone-token: <Keystone Token>
X-Experience-Key: <API_KEY>
X-Experience-Host: demo.ai.example.com
Content-Type: application/json

{
  "model": "demo-model",
  "prompt": "一座山"
}

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{"data":[{"b64_json":"<BASE64_IMAGE>"}]}

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

本地可能返回 400、413、500、502、503；上游 >=400 被包装为 200，请检查 X-Upstream-Status 与 error。

生成语音

功能介绍

生成语音。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/experience/audio/speech

接口请求头

请求头	说明
X-Experience-Host	路由域名。
X-Experience-Key	必选，网关 API Key。

请求消息

请求体由 Beacon 原样转发给后端服务，字段约束以所选服务为准；以下为常见调用格式，非 Beacon 本地校验规则。

字段	类型	说明
model	string	路由提供的模型名称
input	string	待合成文本
voice	string	后端支持的音色
response_format	string	后端支持的音频格式

响应消息

请求示例

POST https://{endpoint}/api/v1/experience/audio/speech
x-keystone-token: <Keystone Token>
X-Experience-Key: <API_KEY>
X-Experience-Host: demo.ai.example.com
Content-Type: application/json

{
  "model": "demo-model",
  "input": "你好",
  "voice": "<VOICE_FROM_CAPABILITIES>"
}

正常响应示例

HTTP/1.1 200 OK
Content-Type: audio/mpeg

<音频字节>

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

本地可能返回 400、413、500、502、503；上游 >=400 被包装为 200，请检查 X-Upstream-Status 与 error。

查询语音模型能力

功能介绍

查询语音模型能力。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/experience/audio/capabilities

查询参数

参数	类型	必选	描述
routeId	string	是	路由 ID
model	string	是	对外模型名称

请求消息

无请求体。

响应消息

参数	参数类型	描述
model	string	对外模型名称
servedModel	string	后端实际模型名；空值时可能省略
providerId	string	外部服务 ID
voices	array	可用音色列表
languages	array	可用语言列表
languageSupported	boolean	是否支持语言参数
defaultLanguage	string	默认语言；空值时可能省略
responseFormats	array	响应编码格式列表
defaultResponseFormat	string	默认响应格式；空值时可能省略
speed	experience.numberRange / null	语速范围；空值时可能省略
discoveryWarnings	array	能力探测提示；空值时可能省略

请求示例

GET https://{endpoint}/api/v1/experience/audio/capabilities?routeId=route-id&model=demo-model
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "model": "",
  "providerId": "providerId-example",
  "voices": [
    ""
  ],
  "languages": [
    ""
  ],
  "languageSupported": true,
  "responseFormats": [
    ""
  ]
}

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

音频转写

功能介绍

音频转写。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/experience/audio/transcriptions

接口请求头

请求头	说明
X-Experience-Host	路由域名。
X-Experience-Key	必选，网关 API Key。

请求消息

请求体由 Beacon 原样转发给后端服务，字段约束以所选服务为准；以下为常见调用格式，非 Beacon 本地校验规则。

表单字段	类型	说明
file	binary	上传音频文件。
model	string	路由提供的模型名称。
language / response_format	string	可选参数，是否支持由后端决定。

响应消息

请求示例

POST https://{endpoint}/api/v1/experience/audio/transcriptions
x-keystone-token: <Keystone Token>
X-Experience-Key: <API_KEY>
X-Experience-Host: demo.ai.example.com
Content-Type: multipart/form-data; boundary=example

--example
Content-Disposition: form-data; name="model"

demo-model
--example
Content-Disposition: form-data; name="file"; filename="audio.wav"
Content-Type: audio/wav

<音频文件二进制>
--example--

正常响应示例

HTTP/1.1 200 OK
Content-Type: application/json

{"text":"你好"}

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

本地可能返回 400、413、500、502、503；上游 >=400 被包装为 200，请检查 X-Upstream-Status 与 error。

查询体验中心可用路由

功能介绍

查询体验中心可用路由。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/experience/routes

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<experience.RouteView>	结果列表

请求示例

GET https://{endpoint}/api/v1/experience/routes
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "status": "ready",
      "projectId": "projectId-example",
      "backend": {
        "catalog": "",
        "type": "",
        "id": "id-example"
      },
      "spec": {}
    }
  ]
}

状态码与错误码

成功状态码：200。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。