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

# 接入配置

> 配置端点、密钥、模型和生产环境调用策略。

生产环境接入 AIOAGI 时，建议把端点、API Key、默认模型和超时策略都配置为环境变量，避免硬编码。

<Info>
  如果你还没有充值和创建令牌，请先阅读 [API Key 全流程指南](/api-key-guide)。本页面向已经拿到可用 Key 的开发接入场景。
</Info>

## 推荐配置项

<ResponseField name="AIO_API_KEY" type="string" required>
  AIOAGI API Key。仅在服务端保存，不要暴露到浏览器、移动端包体或公开仓库。
</ResponseField>

<ResponseField name="AIO_BASE_URL" type="string" required>
  OpenAI 兼容基础地址，例如 `https://api.aiearth.dev/v1`。
</ResponseField>

<ResponseField name="AIO_DEFAULT_MODEL" type="string">
  默认模型名称。建议按业务场景拆分，例如 `AIO_CHAT_MODEL`、`AIO_CODING_MODEL` 和 `AIO_EMBEDDING_MODEL`。
</ResponseField>

<ResponseField name="AIO_TIMEOUT_MS" type="number">
  客户端请求超时时间。生产环境建议设置明确超时，并在失败时进行重试或降级。
</ResponseField>

## 端点策略

<Table>
  <thead>
    <tr>
      <th>端点</th>
      <th>用途</th>
      <th>建议</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>[https://api.aiearth.dev/v1](https://api.aiearth.dev/v1)</code></td>
      <td>通用 API 调用</td>
      <td>默认接入地址</td>
    </tr>

    <tr>
      <td><code>[https://api.aiearth.vip/v1](https://api.aiearth.vip/v1)</code></td>
      <td>CDN 加速 API 调用</td>
      <td>适合对网络链路敏感的服务</td>
    </tr>

    <tr>
      <td><code>[https://api-s1.aiearth.dev/v1](https://api-s1.aiearth.dev/v1)</code></td>
      <td>余额查询、实时语音等能力</td>
      <td>按控制台说明启用</td>
    </tr>
  </tbody>
</Table>

## 生产建议

* 对用户输入进行长度限制，避免超长上下文导致成本不可控。
* 为每个业务线使用独立 Token 组，便于额度控制和账单追踪。
* 记录请求 ID、模型、耗时、Token 用量和错误码，便于排查问题。
* 对高频任务设置重试、熔断和降级模型。
* 不要在日志中打印完整 API Key 或敏感用户内容。

## 上线前检查

* 令牌所在分组支持你配置的默认模型。
* 余额和单 Key 额度上限充足。
* 应用里填写的是正确端点，必要时包含 `/v1`。
* 失败重试不会对非幂等操作造成重复执行。
* 浏览器和移动端不会直接暴露服务端 Key。

## 客户端初始化模板

```typescript theme={null}
import OpenAI from "openai";

export const aiClient = new OpenAI({
  apiKey: process.env.AIO_API_KEY,
  baseURL: process.env.AIO_BASE_URL ?? "https://api.aiearth.dev/v1",
  timeout: Number(process.env.AIO_TIMEOUT_MS ?? 60000),
});
```

<Warning>
  如果你在边缘函数或浏览器环境中调用模型，请通过自有后端转发请求。不要把 API Key 下发到客户端。
</Warning>