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

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

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

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

<API_BASE_URL>/v1/chat/completions

常见错误配置

使用了文档站域名作为 API 地址

错误示例：

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

正确示例：

# ✅ 正确：使用 API 服务地址
base_url = "<API_BASE_URL>/v1"

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

缺少 /v1 路径前缀（导致 404）

错误示例：

# ❌ 错误：缺少 /v1 前缀
base_url = "<API_BASE_URL>"

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

出现重复的 /v1/v1（使用 openai SDK 时常见）

错误示例：

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

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

使用了 HTTP 而非 HTTPS

错误示例：

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

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

openai SDK 配置方法

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)

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);

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

验证配置是否正确

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

curl <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"

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

相关资源

​常见错误配置

​openai SDK 配置方法

​验证配置是否正确

常见错误配置

openai SDK 配置方法

验证配置是否正确