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

# 为什么提示 API Key 无效？

> 解决 API Key 无效错误，了解 Base URL 和 API Key 的正确配置方法

## 常见错误现象

当您看到类似以下错误信息时：

```json theme={null}
{
  "error": {
    "message": "Incorrect API key provided: sk-QqHvK***...",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

这通常**不是**您的 API Key 本身有问题，而是**请求地址（Base URL）配置错误**导致的。

<Warning>
  最常见的错误：使用了 GravitexAI 的 Key，但请求地址仍然指向 OpenAI 官网 `https://api.openai.com`
</Warning>

## 什么是 Base URL？

**Base URL**（基础 URL / 请求地址）是 API 请求的目标服务器地址。不同的 API 服务提供商使用不同的 Base URL。

### Base URL 和 API Key 必须一一对应

| 服务提供商            | Base URL                                           | API Key 格式 | 是否匹配     |
| ---------------- | -------------------------------------------------- | ---------- | -------- |
| **GravitexAI**   | [https://api.gravitex.ai](https://api.gravitex.ai) | sk-xxxx... | ✅ 正确     |
| **OpenAI 官方**    | [https://api.openai.com](https://api.openai.com)   | sk-xxxx... | ✅ 正确     |
| ❌ GravitexAI Key | [https://api.openai.com](https://api.openai.com)   | sk-xxxx... | ❌ **错误** |
| ❌ OpenAI Key     | [https://api.gravitex.ai](https://api.gravitex.ai) | sk-xxxx... | ❌ **错误** |

<Note>
  关键原则：使用哪家的 API Key，就必须将请求发送到对应服务商的 Base URL
</Note>

## 正确的配置方法

### 方法一：修改 Base URL（推荐）

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="sk-your-gravitex-key",  # GravitexAI 后台获取的 Key
        base_url="https://api.gravitex.ai/v1"  # 改为 GravitexAI 地址
    )

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "你好"}]
    )
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    import OpenAI from 'openai';

    const client = new OpenAI({
      apiKey: 'sk-your-gravitex-key',
      baseURL: 'https://api.gravitex.ai/v1'
    });

    const response = await client.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: '你好' }]
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.gravitex.ai/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-your-gravitex-key" \
      -d '{
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "你好"}]
      }'
    ```
  </Tab>
</Tabs>

### 方法二：使用环境变量

<Tabs>
  <Tab title="Linux/macOS">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-your-gravitex-key"
    export OPENAI_BASE_URL="https://api.gravitex.ai/v1"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $env:OPENAI_API_KEY="sk-your-gravitex-key"
    $env:OPENAI_BASE_URL="https://api.gravitex.ai/v1"
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd theme={null}
    set OPENAI_API_KEY=sk-your-gravitex-key
    set OPENAI_BASE_URL=https://api.gravitex.ai/v1
    ```
  </Tab>
</Tabs>

## 支持的请求地址格式

| 格式           | 地址                                            | 适用场景    |
| ------------ | --------------------------------------------- | ------- |
| 带 /v1（推荐）    | `https://api.gravitex.ai/v1`                  | 大多数代码库  |
| 带 /v1/（末尾斜杠） | `https://api.gravitex.ai/v1/`                 | 某些框架要求  |
| 完整路径         | `https://api.gravitex.ai/v1/chat/completions` | cURL 请求 |

## 常见问题排查

<AccordionGroup>
  <Accordion title="确认修改了 Base URL，但仍然报错">
    **可能原因**：

    1. **代码中有多处配置**：检查配置文件、环境变量、代码初始化等
    2. **使用了代理或中间件**：某些代理工具可能会重定向请求
    3. **缓存问题**：重启程序或清除缓存后重试
    4. **拼写错误**：确认地址拼写正确
  </Accordion>

  <Accordion title="如何确认 Key 是否有效？">
    在 GravitexAI 后台查看：

    1. 登录 [GravitexAI 控制台](https://maas.gravitex.ai)
    2. 进入「令牌」页面
    3. 检查 Key 状态是否为「启用」
    4. 确认账户余额充足
  </Accordion>

  <Accordion title="使用第三方工具如何配置？">
    大多数第三方工具都有「自定义 API」选项：

    * **API 地址 / Base URL**：`https://api.gravitex.ai/v1`
    * **API Key**：从 GravitexAI 后台复制您的 Key
    * **模型名称**：参考模型列表
  </Accordion>
</AccordionGroup>

## 错误示例 vs 正确示例

### ❌ 错误配置

```python theme={null}
client = OpenAI(
    api_key="sk-gravitex-key",
    base_url="https://api.openai.com/v1"
    # ❌ 使用了 OpenAI 官网地址
)
```

**结果**：OpenAI 服务器会拒绝 GravitexAI 的 Key

### ✅ 正确配置

```python theme={null}
client = OpenAI(
    api_key="sk-gravitex-key",
    base_url="https://api.gravitex.ai/v1"
    # ✅ 使用 GravitexAI 地址
)
```

**结果**：请求成功发送到 GravitexAI 服务器

## 快速测试方法

使用 cURL 命令快速验证配置是否正确：

```bash theme={null}
curl https://api.gravitex.ai/v1/models \
  -H "Authorization: Bearer sk-your-gravitex-key"
```

**预期结果**：返回可用模型列表

```json theme={null}
{
  "data": [
    {
      "id": "gpt-4o",
      "object": "model"
    }
  ]
}
```

如果返回错误，请检查：

1. API Key 是否正确复制（注意首尾空格）
2. 网络连接是否正常
3. 账户余额是否充足

<Tip>
  记住核心原则：哪家的 Key 配哪家的 URL，GravitexAI 的 Key 就用 `https://api.gravitex.ai/v1`
</Tip>