> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 将共享偏好绑定到密钥

> 将已有的路由工作室偏好绑定到某个 API 密钥，或清除绑定。

管理 API 密钥与**共享**路由工作室偏好（跨多个密钥使用，或作为团队默认值的偏好）之间的绑定关系。如果需要更简单的、直接在密钥上编辑规则的密钥优先方式，请参见 [`/api/v1/keys/{id}/routing-rules`](/api-reference/routing-preferences/key-routing-rules)。

将 `preference_id` 设为 null 即可清除绑定；此后该密钥在请求时将按顺序继承组织默认值 → 用户默认值 → 无。

## 身份验证

需要携带具有 `billing` API 密钥作用域的 Bearer 令牌，并且调用方需拥有对该密钥的访问权限（调用方本人拥有该密钥，或通过所在活跃组织获得访问权限）。

## GET

读取当前的绑定关系。

```bash theme={null}
curl https://www.hitheo.ai/api/v1/keys/{id}/routing-preference \
  -H "Authorization: Bearer $THEO_API_KEY"
```

```typescript theme={null}
const { preference_id, inherits_default } = await theo.keys.getRoutingPreference(keyId);
```

```json theme={null}
{
  "key_id": "key_abc",
  "preference_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e",
  "inherits_default": false
}
```

## PUT

设置或清除绑定关系。

<ParamField body="preference_id" type="string">
  偏好的 UUID。传入 `null` 可清除绑定。
</ParamField>

```bash theme={null}
# 绑定一个偏好
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/routing-preference \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preference_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e" }'

# 清除绑定
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/routing-preference \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preference_id": null }'
```

```typescript theme={null}
await theo.keys.setRoutingPreference(keyId, "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e");
await theo.keys.setRoutingPreference(keyId, null); // 清除
```

## 作用域规则

* 个人偏好只能绑定到其创建者本人拥有的密钥。
* 团队偏好只能绑定到同一组织内的密钥。
* 跨越该边界会返回 `400 routing_preference_not_bindable`，并附带与厂商无关的提示信息。

## 错误

* `400 routing_preference_not_bindable` — 该偏好对该密钥的作用域不可见。
* `404 not_found` — 密钥或偏好不存在（或调用方不可见）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.