> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/tinyhumans-api-key.md).

# 一个 TinyHumans API 密钥

一个 TinyHumans API 密钥能解锁什么、如何使用它，以及 OpenHuman 如何存储和发送它。

一个 TinyHumans 凭证即可解锁所有托管后端服务：通过 OpenRouter 模型目录进行聊天推理、网页搜索、嵌入、媒体生成、集成、语音以及 Jev 排序器。每项服务都不需要单独的密钥。桌面应用会在你登录时获取该凭证。库宿主或无头进程会直接提供它。

## 如何获取一个

所有托管服务都位于一个 TinyHumans 账户之后。通过桌面应用登录即可获取会话凭证，或者生成一个 API 密钥（`th_...`）供库和无头使用。

## 使用方式

桌面应用：使用 TinyHumans 账户登录。应用会将会话凭证存储在由操作系统支持的 auth-profile 存储中。核心组件会以解析 API 密钥的相同方式来解析它，通过 `security::credentials::api_key` 和 `session_support::resolve_backend_credential`.

库：将密钥传递给 `RuntimeBuilder` 然后它会以连接状态启动：

```rust
use openhuman_tinyhumans::{embed::Workspace, RuntimeBuilder};

let runtime = RuntimeBuilder::new()
    .workspace(Workspace::Ephemeral)
    .api_key("th_...")
    .build()
    .await?;
```

`openhuman_tinyhumans::RuntimeBuilder` 镜像 `openhuman_embed::RuntimeBuilder` 按方法逐一映射。对于 `build()` 它会安装由 SDK 支持的传输层并将其绑定到运行时。

无头：设置 `OPENHUMAN_BACKEND_API_KEY` 在核心启动之前。启动序列（`crates/openhuman-core/src/security/credentials/ops/boot_env.rs`）会将其安装到一个全新的凭证存储中，并且绝不会覆盖已存在的凭证。

## 它存储在哪里以及如何发送

该密钥与应用会话一样存储在同一个 auth-profile 存储中，位于其自己的 provider id（`api-key`）。它绝不会写入 `config.toml` ，也绝不会被记录。它是库嵌入方持有的唯一凭证。没有登录令牌交换，没有会话 JWT，也没有 `/auth/me` 往返请求。

根据端点不同，该密钥会以以下两种形式之一发送：

* 托管推理（`{api_url}/openai/v1`): `Authorization: Bearer <key>`. `OpenHumanBackendModel::resolve_bearer` 当两者都存在时，会优先使用存储的 API 密钥而不是应用会话。
* 后端 REST（`BackendClient`, `IntegrationClient`): `x-api-key: <key>`.

`crates/openhuman-core/src/security/credentials/api_key.rs` 负责存储和检索（`store_api_key`, `get_api_key`, `has_api_key`, `clear_api_key`). `session_support::BackendCredential` 在请求时将任一凭证形式转换为正确的标头。

## 使用你自己的密钥仍然可行

API 密钥覆盖托管路径。你仍然可以将任何工作负载指向你自己的提供方：聊天和推理指向一个自带密钥的 LLM slug，嵌入直接使用 Voyage、OpenAI 或 Cohere，搜索直接使用 Brave、Exa 或 Tavily。参见 [可插拔引擎](/openhuman/zh/kai-fa/engines.md) 以获取完整列表以及每项对应的配置键。使用你自己的密钥运行全部功能不需要 TinyHumans 密钥。通过托管后端运行任何功能则需要。