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

# SDK

> Avala API 的官方 SDK 和客户端库

Avala 提供官方 SDK 和客户端库，帮助您从首选语言或框架集成平台。每个 SDK 都使用符合语言习惯的方法封装 Avala REST API，内置认证、自动重试和完整的类型安全。

## 客户端库

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="/docs/zh/sdks/python">
    同步和异步支持。完整类型提示。Python 3.9+。
  </Card>

  <Card title="TypeScript" icon="js" href="/docs/zh/sdks/typescript">
    完全类型化。零依赖。适用于 Node.js、Deno 和 Bun。
  </Card>

  <Card title="CLI" icon="terminal" href="/docs/zh/sdks/cli">
    从终端管理数据集、导出和存储。`curl -fsSL https://avala.ai/install.sh | bash`。
  </Card>

  <Card title="REST API" icon="globe" href="/docs/sdks/rest-api">
    使用 HTTP 请求从任何语言直接使用 API。
  </Card>

  <Card title="OpenAPI" icon="code" href="/docs/sdks/openapi">
    从 OpenAPI 规范生成您自己的客户端。
  </Card>
</CardGroup>

## 快速对比

| 功能       | Python              | TypeScript                  | CLI                                              | REST API |
| -------- | ------------------- | --------------------------- | ------------------------------------------------ | -------- |
| **安装**   | `pip install avala` | `npm install @avala-ai/sdk` | `curl -fsSL https://avala.ai/install.sh \| bash` | 直接 HTTP  |
| **异步**   | 同步 + 异步             | 异步                          | 不适用                                              | 任何       |
| **类型安全** | 完整类型提示              | 完整 TypeScript 类型            | 不适用                                              | 不适用      |
| **自动重试** | 是                   | 是                           | 通过 SDK                                           | 手动       |
| **分页**   | 内置迭代器               | 内置迭代器                       | `--limit` 标志                                     | 手动       |
| **依赖**   | httpx、pydantic      | 无（原生 fetch）                 | click、rich                                       | 不适用      |

## 环境变量

所有 SDK 都遵循以下环境变量，因此您可以一次配置并在整个技术栈中使用。

| 变量               | 描述                                        | 默认值                           |
| ---------------- | ----------------------------------------- | ----------------------------- |
| `AVALA_API_KEY`  | 用于认证的 Avala API 密钥。如果未传递密钥给客户端构造函数，则自动使用。 | 无（必需）                         |
| `AVALA_BASE_URL` | 覆盖默认 API 基础 URL。适用于自托管部署或开发环境。            | `https://api.avala.ai/api/v1` |

## 认证

对 Avala API 的所有请求必须在 `X-Avala-Api-Key` 头中包含 API 密钥。您可以在 [Avala 仪表板](https://avala.ai/settings?section=security)的 **设置 > 安全** 中找到 API 密钥。

```bash theme={null}
export AVALA_API_KEY="your-api-key"
```

设置环境变量后，所有 SDK 将自动使用，无需额外配置。

## MCP 集成

通过 [Model Context Protocol](/docs/integrations/mcp-setup) 使用 Avala 与 Claude、Cursor 和 VS Code 等 AI 助手配合使用。`@avala-ai/mcp-server` 包将您的数据集、项目和导出作为 AI 助手可以直接调用的工具暴露。