# 更新账户偏好

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

1. 准备用于当前账号认证的个人访问令牌或服务账号访问令牌，凭据说明见[访问凭据](../../../../../guides/billing/credentials.md#choose-credential-type)。本接口直接修改当前账号偏好，不需要提供工作区 ID。
2. 如需确认当前已生效的语言与时区设置，可先[查询账户偏好](get-account-preferences.md)。

## 请求体

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

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
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"
  }'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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` 字段。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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` 字段。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码，例如 `ErrParamInvalid`、`ErrMultipleAuthCredentials`、`Unauthorized`、`unauthenticated`、`ErrForbidden` 或 `ErrServiceUnavailable`。 |
| `msg` | string | 错误说明文本。 |

:::::
::::::
:::::::
