请求结构

Beacon API 通过平台提供的访问地址接收 HTTP 请求。请求使用 GET、POST、PUT、PATCH 或 DELETE 方法，具体方法以接口说明为准。查询参数应放在 URL 中。以下示例使用当前环境的 Beacon 接入路径。

结构示例

以下为请求 URL 示例：

https://{IP地址}/beacon/api/v1/models?page=1&page_size=20

https 为当前环境使用的通信协议。
{IP地址} 为平台提供的访问地址；如需指定端口，应写在 IP 地址之后。
/beacon 为当前环境对外提供的 Beacon 访问前缀。
/api/v1/models 为模型列表接口路径。
page=1&page_size=20 为查询参数，多个参数使用 & 连接；参数值中的特殊字符应进行 URL 编码。

通信协议

当前环境通过 HTTPS 对外提供 Beacon API。其他部署环境的协议以平台管理员提供的访问地址为准；传输登录令牌、API Key 等敏感信息时应使用 HTTPS。

服务网址

当前环境的 Beacon 对外访问基地址为 https://{IP地址}/beacon。请向平台管理员确认实际 IP 地址和端口。

产品接口路径统一以 /api/v1 开头。将对外访问基地址与接口详情中的路径拼接即可，不要重复添加 /beacon 或 /api/v1。例如，GET /api/v1/models 对应 GET https://{IP地址}/beacon/api/v1/models；GET /api/v1/health 对应 GET https://{IP地址}/beacon/api/v1/health。

其他接口文档中的 https://{endpoint}/api/v1/... 为同一接入方式的简写：在当前环境，{endpoint} 应替换为 {IP地址}/beacon，不能只替换为 IP 地址。模型上传涉及的内部回调由平台服务调用，开发者无需直接请求。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

方法	说明
GET	查询指定资源；返回内容以具体接口说明为准。
PUT	向指定资源提交配置，更新或替换的范围以具体接口说明为准。
POST	创建资源、提交任务或执行指定操作。
PATCH	对指定资源进行部分更新，通常只修改请求中提供的字段。
DELETE	请求服务器删除指定资源。

字符编码

请求及返回结果都使用UTF-8字符集编码。文件、音频等二进制内容按具体接口约定传输。

公共参数

公共参数用于描述请求内容、身份认证和请求追踪。各参数的适用条件如下；接口特有参数在对应接口中说明。

参数必选性

参数表中的“是”表示完成该业务操作应提供的字段；“条件必选”表示满足描述中的条件时必须提供；“否”表示可省略。系统或客户端自动填充的必选字段仍应出现在最终请求中，默认选项不等于允许提交空值。

必选性按完整业务配置约定说明，不代表服务端对所有缺失字段均已实施强制校验。嵌套字段的必选性以使用其所属对象为前提。PATCH 接口允许省略未修改字段，但更新后的资源仍须满足业务约束；不能将完整编辑表单的必填项直接解释为每次 PATCH 都必须提交。

公共请求参数

名称	类型	是否必选	描述
Host	String	是	请求的服务器信息，从服务API的URI中获取，值为hostname[:port]，通常由HTTP客户端自动设置。
x-keystone-token	String	使用 Token 认证时必选	有效的 Keystone Token，直接填写 Token 值，不添加 Bearer 前缀。
Content-Type	String	有请求体时按接口要求	JSON请求使用application/json；音频转写使用带boundary的multipart/form-data。
Content-Length	String	否	请求body长度，单位为Byte，通常由HTTP客户端自动计算。
X-Request-Id	String	否	请求追踪标识。
X-Experience-Key	String	模型体验接口按要求提供	用于访问模型网关的API Key。
X-Experience-Host	String	模型体验接口按要求提供	用于选择目标路由域名。

项目与部门上下文来自登录身份，不能通过添加项目查询参数或请求头任意切换资源归属。内部上传回调的共享密钥要求见对应接口。

公共返回参数

参数名称	参数类型	描述
X-Request-Id	String	响应头中的请求追踪标识。
request_id	String	普通资源接口错误响应中的请求追踪标识；是否出现以具体响应为准。
Content-Type	String	响应内容类型，例如application/json、text/event-stream或音频类型。

身份认证

Beacon 管理接口使用 Keystone Token识别调用者；无需认证的接口以各接口说明为准。Token由平台身份认证流程提供，Beacon 的当前用户接口只查询登录身份，不签发令牌。调用需要认证的管理接口时，在请求头中添加 x-keystone-token: <Keystone Token>；通过平台网关访问Beacon管理接口时，使用有效的Keystone Token，在请求头中添加x-keystone-token: ，不添加Bearer前缀。Token由平台身份认证服务签发，应具有目标项目的作用域。Beacon当前用户接口仅查询登录身份，不签发令牌。也支持使用平台登录后的有效会话Cookie访问。

GET https://{IP地址}/beacon/api/v1/me
x-keystone-token: <Keystone Token>
X-Request-Id: beacon-doc-example

认证通过后，平台根据用户角色、项目、资源所有权及共享关系检查操作权限。读取与修改操作需要相应授权，具体访问要求见各接口说明。网关API Key用于模型服务调用，不能替代管理接口的Token。

返回结果

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态。为了便于查看，API文档返回示例均有换行和缩进等处理。示例中的地址、ID、令牌及业务数据仅用于说明，请按实际调用替换。

正确返回结果

普通接口调用成功时，HTTP状态码为2xx，响应体包含具体接口约定的数据。204表示成功且无响应体；WebSocket升级和缓存校验按各接口约定返回。

以获取当前登录用户为例，调用成功可能返回：

{
  "id": "user-example",
  "name": "示例用户",
  "email": "user@example.com",
  "roles": ["member"],
  "domainId": "domain-example",
  "domainName": "示例部门",
  "projectId": "project-example",
  "projectName": "示例项目"
}

异步任务已接受或创建成功，不表示模型服务已经就绪，应继续查询任务或部署状态。分页参数及默认值以各列表接口为准；部分更新时，省略字段表示不修改该项，空字符串、空数组与null的含义以具体字段说明为准。

错误返回结果

普通资源接口错误通常包含error、message和request_id，部分错误还包含details。例如：

{
  "error": "invalid_request",
  "message": "name is required",
  "request_id": "beacon-doc-example"
}

认证失败可返回error和login_url；模型体验及内部回调的错误格式见各接口说明。模型体验的上游错误可能以HTTP 200返回，需要结合响应体中的error和响应头X-Upstream-Status判断结果。

公共错误码

状态码	含义
400	请求参数或格式错误。
401	未认证或登录令牌无效。
403	无权执行该操作。
404	请求的资源或接口不存在。
409	资源引用、状态或容量冲突。
413	请求体过大。
422	请求未通过业务校验。
500	服务内部错误。
502	下游服务异常。
503	服务或其依赖暂不可用。

具体错误码和触发条件以各接口说明为准。

调用方式