安装

安装

TypeScript

npm install @imbrace/sdk
# 或
yarn add @imbrace/sdk
# 或
pnpm add @imbrace/sdk

需要 Node.js 18+（或任何支持原生 fetch 和 ReadableStream 的浏览器）。

Python

pip install imbrace
# 或
uv add imbrace

需要 Python 3.9+。

初始化客户端

TypeScript

import { ImbraceClient } from "@imbrace/sdk"

// 构建在 Imbrace 之上 — Imbrace 就是你的后端，终端用户通过 OTP 登录
const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env: "stable",
})

客户端是有状态的 — 创建一次并在整个应用中重复使用。

Python

import os
from imbrace import ImbraceClient

# 构建在 Imbrace 之上 — Imbrace 就是你的后端，终端用户通过 OTP 登录
with ImbraceClient(
    access_token=os.environ["IMBRACE_ACCESS_TOKEN"],
    env="stable",
) as client:
    me = client.platform.get_me()

Python 还导出了 AsyncImbraceClient（async with ...），适用于 FastAPI 等异步框架。

上下文管理器会自动关闭底层的 HTTP 连接池。

TypeScript

import { ImbraceClient } from "@imbrace/sdk"

// 包装 Imbrace — Imbrace 是你后端中的一个功能，你的用户
const client = new ImbraceClient({
  apiKey:         process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env:            "stable",
})

客户端是有状态的 — 创建一次并在整个应用中重复使用。

Python

import os
from imbrace import ImbraceClient

# 包装 Imbrace — Imbrace 是你后端中的一个功能，你的用户
with ImbraceClient(
    api_key=os.environ["IMBRACE_API_KEY"],
    organization_id=os.environ.get("IMBRACE_ORGANIZATION_ID"),
    env="stable",
) as client:
    me = client.platform.get_me()

Python 还导出了 AsyncImbraceClient（async with ...），适用于 FastAPI 等异步框架。

上下文管理器会自动关闭底层的 HTTP 连接池。

关于何时使用每种凭证，请参见认证。关于凭证设置的分步指南（环境变量、dotenv、密钥），请参见设置指南。

验证

TypeScript

import { ImbraceClient } from "@imbrace/sdk"
console.log("SDK loaded:", typeof ImbraceClient) // "function"

Python

from imbrace import ImbraceClient
print("SDK ready:", ImbraceClient)

环境变量

SDK 不会自动读取环境变量。请直接将凭证传递给构造函数，如果你将它们保存在 .env 中，请使用加载器（dotenv / 你框架的环境变量处理方式）。

变量	用途
IMBRACE_API_KEY	你的 API Key（组织级凭证）
IMBRACE_ACCESS_TOKEN	用户的访问令牌（每会话凭证）
IMBRACE_ORGANIZATION_ID	组织 ID — 在每个请求中作为 x-organization-id 传递
IMBRACE_GATEWAY_URL	覆盖网关 URL（默认：https://app-gatewayv2.imbrace.co）

组织 ID 编码在 API Key 和访问令牌内部。你可以选择性地通过向构造函数传递 organizationId（TypeScript）或 organization_id（Python）来覆盖它。详情请参见认证。

---

下一步

• 快速入门 → — 在 60 秒内完成你的第一次 API 调用
• 认证 → — 凭证类型、OTP 登录流程以及何时使用每种凭证
• 设置指南 → — 环境、环境变量和服务 URL 覆盖