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

# HHAPI Base URL 配置详解：/v1 路径前缀要求与常见错误

> 正确配置 HHAPI 的 Base URL 和 /v1 路径前缀，避免因使用文档站域名、缺少路径前缀或出现重复 /v1/v1 等错误导致请求返回 404 或连接失败。

Base URL 配置错误是新用户接入 HHAPI 时最常见的问题之一。一个多余的路径前缀、一处拼写错误或者使用了错误的域名，都会导致请求返回 404 或连接失败。本文说明正确的 Base URL 格式，以及各类 SDK 的配置方式。

<Warning>
  `docs.hhapi.xyz` 是 **文档站域名**，不是 API 请求地址。请勿将文档站地址用于发送 API 请求，否则所有请求都会失败。
</Warning>

<Note>
  所有 API 请求应发往 `<API_BASE_URL>`，请求路径以 `/v1` 开头。例如，Chat Completions 接口的完整地址为：

  ```
  <API_BASE_URL>/v1/chat/completions
  ```
</Note>

## 常见错误配置

<AccordionGroup>
  <Accordion title="使用了文档站域名作为 API 地址">
    **错误示例：**

    ```python theme={null}
    # ❌ 错误：使用了文档站域名
    base_url = "https://docs.hhapi.xyz/v1"
    ```

    **正确示例：**

    ```python theme={null}
    # ✅ 正确：使用 API 服务地址
    base_url = "<API_BASE_URL>/v1"
    ```

    文档站（`docs.hhapi.xyz`）仅用于浏览开发文档，不处理任何 API 请求。
  </Accordion>

  <Accordion title="缺少 /v1 路径前缀（导致 404）">
    **错误示例：**

    ```python theme={null}
    # ❌ 错误：缺少 /v1 前缀
    base_url = "<API_BASE_URL>"
    ```

    所有 HHAPI 接口均挂载在 `/v1` 路径下。缺少该前缀会导致服务端返回 404 Not Found。
  </Accordion>

  <Accordion title="出现重复的 /v1/v1（使用 openai SDK 时常见）">
    **错误示例：**

    ```python theme={null}
    # ❌ 错误：base_url 已含 /v1，SDK 不会再追加；
    # 但如果手动拼接了 /chat/completions，路径会错乱
    base_url = "<API_BASE_URL>/v1/chat/completions"
    ```

    openai SDK 会根据调用的方法自动在 `base_url` 后追加对应路径（如 `/chat/completions`）。`base_url` 只需设置到 `/v1` 即可，**不需要**再手动拼接具体接口路径。
  </Accordion>

  <Accordion title="使用了 HTTP 而非 HTTPS">
    **错误示例：**

    ```python theme={null}
    # ❌ 错误：使用了不安全的 HTTP 协议
    base_url = "http://<API_BASE_URL>/v1"
    ```

    HHAPI 仅接受 HTTPS 请求。使用 HTTP 可能导致连接被拒绝，同时存在密钥泄露的安全风险。
  </Accordion>
</AccordionGroup>

## openai SDK 配置方法

<CodeGroup>
  ```python Python theme={null}
  import os
  import openai

  client = openai.OpenAI(
      api_key=os.environ.get("HHAPI_API_KEY"),
      # ✅ base_url 设置到 /v1，SDK 会自动追加接口路径
      base_url="<API_BASE_URL>/v1"
  )

  response = client.chat.completions.create(
      model="<MODEL_ID>",
      messages=[{"role": "user", "content": "你好"}]
  )
  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.HHAPI_API_KEY,
    // ✅ baseURL 设置到 /v1，SDK 会自动追加接口路径
    baseURL: "<API_BASE_URL>/v1",
  });

  const response = await client.chat.completions.create({
    model: "<MODEL_ID>",
    messages: [{ role: "user", content: "你好" }],
  });
  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

<Note>
  openai SDK 会根据调用的方法自动追加路径。例如调用 `client.chat.completions.create()` 时，SDK 内部会请求 `<API_BASE_URL>/v1/chat/completions`。你**不需要**在 `base_url` 中手动加上 `/chat/completions`。
</Note>

## 验证配置是否正确

使用以下 curl 命令快速验证 Base URL 和 API Key 配置是否生效：

```bash theme={null}
curl <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

若返回包含模型列表的 JSON 响应，说明 Base URL 和鉴权配置均正确。若返回 404，请检查路径是否包含 `/v1`；若返回 401，请检查 API Key 格式。

***

**相关资源**

* [获取和管理 API Key](/api-key)
* [模型列表](/models/list)
* [获取技术支持](/support)