更新账户偏好

按字段局部更新当前认证账号的界面语言或 IANA 时区偏好,并返回更新后的完整偏好快照。未传入的字段保持原值不变。

PATCH https://api.moi.matrixorigin.cn/v5/auth/preferences

调用前准备

  1. 准备用于当前账号认证的个人访问令牌或服务账号访问令牌,凭据说明见访问凭据。本接口直接修改当前账号偏好,不需要提供工作区 ID。

  2. 如需确认当前已生效的语言与时区设置,可先查询账户偏好。

请求体

将 $AI_STUDIO_API_KEY 替换为实际凭据。请求可通过 X-API-Key、Authorization: Bearer 或浏览器登录会话(需同时携带 X-CSRF-Token)完成认证;同一请求只能携带一种凭据,且不需要传入 X-Workspace-ID。

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/auth/preferences" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai"
  }'

参数

类型

是否必填

说明

locale

string

否

账号界面语言标识。支持 zh-CN、en-US、fr-FR、es-ES、ar、id-ID;省略时保留当前语言设置。

timezone

string

否

账号时区,必须为有效的 IANA 时区名称(例如 Asia/Shanghai、UTC、America/New_York),不支持 +08:00、UTC+08:00、GMT+08:00 等固定偏移格式;省略时保留当前时区设置。

请求体大小上限为 1 MiB(1048576 字节),且至少需要提供 locale 或 timezone 中的一项。提交空对象 {}、未定义的 JSON 字段、尾随的多余 JSON 内容,或不被支持的语言与时区值时,接口返回 HTTP 400(ErrParamInvalid)。

成功响应

更新成功时返回 HTTP 200,响应头包含 Cache-Control: no-store。顶层响应对象仅包含 code 和 data,不返回 msg 字段。

{
  "code": "OK",
  "data": {
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai",
    "updated_at": "2026-10-14T08:05:00Z"
  }
}

字段

类型

说明

code

string

请求处理成功时固定为 OK。

data

object

更新后的账号偏好设置。

data.locale

string

更新后生效的账号界面语言标识,取值为 zh-CN、en-US、fr-FR、es-ES、ar 或 id-ID。

data.timezone

string

更新后生效的账号 IANA 时区名称,例如 Asia/Shanghai 或 UTC。

data.updated_at

string

偏好最近更新时间,采用 RFC 3339 格式。

错误响应

请求体为空对象 {}、包含未知字段或尾随 JSON 内容、超出 1 MiB,或 locale、timezone 取值不受支持时返回 HTTP 400(ErrParamInvalid);同一请求混用多种认证凭据时返回 HTTP 400(ErrMultipleAuthCredentials);凭据缺失或无效时返回 HTTP 401(Unauthorized 或 unauthenticated);浏览器会话缺少有效 X-CSRF-Token 时返回 HTTP 403(ErrForbidden);上游账户偏好服务不可用时返回 HTTP 502(ErrServiceUnavailable)。错误响应仅包含 code 和 msg,不返回 data 字段。

{
  "code": "ErrParamInvalid",
  "msg": "Bad Request"
}

字段

类型

说明

code

string

错误代码,例如 ErrParamInvalid、ErrMultipleAuthCredentials、Unauthorized、unauthenticated、ErrForbidden 或 ErrServiceUnavailable。

msg

string

错误说明文本。

最后更新于