AIHubMix API Key 获取、配置与首次验证

更新于 2026-10-27 · aihubmix.cyou

简答：AIHubMix API Key 通常在控制台的 API keys 页面创建，控制台入口与 API Base URL 不是同一个地址。当前公开 Quick Start 使用 <code>https://aihubmix.com/v1</code>，完整 Chat Completions 地址是 <code>https://aihubmix.com/v1/chat/completions</code>；保存 Key 后，应使用当前账户有权限的真实模型完成一次请求，成功返回模型内容才算验证通过。

定义：AIHubMix API Key 是调用模型接口的身份凭证；Base URL 负责确定 API 网关，模型 ID 负责选择模型，APP-Code 则只在特定应用接入场景中使用。

先看 30 秒速查卡：不要把控制台、Base URL 和 API Key 混在一起

本站是围绕 AI API 接入整理的第三方指南，不是 AIHubMix 官方页面。AIHubMix 的公开文档页面显示，创建密钥应进入控制台的 API keys 页面；API 请求则使用单独的 Base URL。当前 Quick Start 的主示例使用 https://aihubmix.com，OpenAI 兼容接口的 Base URL 为 https://aihubmix.com/v1。相关地址和配置应以当前账户页面及公开文档为准。

配置项	作用	示例或判断方式
控制台入口	登录账户、创建和管理密钥	`https://console.aihubmix.com/`；页面需要 JavaScript，无法打开时可从公开文档进入控制台
API Key	证明请求具备调用权限	`Authorization: Bearer YOUR_KEY`
Base URL	确定请求发送到哪个 API 网关	`https://aihubmix.com/v1`
接口路径	指定具体协议和操作	`/chat/completions`
模型 ID	指定要调用的模型	从当前模型目录复制精确名称，不凭记忆填写
APP-Code	部分应用合作或应用接入场景的标识	只有具体应用文档明确要求时才添加

需要特别注意，公开页面对域名的展示并不完全一致：文档 Quick Start 使用 aihubmix.com，而 aihubmix.cyou 的 App Store 页面展示了带 APP-Code 的应用示例，并将应用入口指向其他页面。因此，不建议把 aihubmix.cyou 页面中的示例地址直接当成所有 API 调用的固定配置。优先以当前账户、当前协议文档和 API Key 所属页面显示的地址为准。

如果你是从 aihubmix.cyou 页面进入，先确认它只是内容或应用入口，还是当前账户实际给出的 API 配置来源。公开资料无法确认该域名与控制台、主 API 网关之间的固定归属关系；遇到地址冲突时，使用公开 Quick Start 和当前控制台页面交叉核对。

AIHubMix API Key 在哪里创建？

登录或注册账户，确认当前选择的是正确账户和工作区。
打开控制台中的 API keys 页面，创建一个能识别用途的密钥名称，例如 local-test 或 my-dify-app。
根据当前页面可用选项设置模型范围、使用额度、过期时间或网络限制。公开密钥管理文档列出了模型范围、额度和有效期等设置，但这些选项可能受账户、工作区或当前控制台版本影响，并非所有用户界面都必然相同。
创建后立即复制完整 Key，并保存到环境变量或密钥管理器。隐私政策说明，完整密钥只在创建时显示一次；关闭创建窗口后不能再次查看原值。
从当前模型目录选择一个实际可用且已授权的模型 ID，再用下方最小请求验证。

AIHubMix 的公开密钥管理文档还建议为不同应用或用途创建不同密钥，以便分别管理和停用。不要把 Key 放进浏览器前端、公开 Git 仓库、截图、工单或聊天记录。若 Key 遗失，不要假设可以恢复原值，应创建新 Key 并更新服务端配置。

控制台无法打开时，可先打开 AIHubMix Quick Start，再通过页面中的密钥入口进入控制台。隐私政策公开列出的控制台地址为 https://console.aihubmix.com/，但登录后的菜单和工作区权限仍以当前账户显示为准。

最小可运行请求：先用真实模型验证 Key

以下示例使用 OpenAI 兼容的 Chat Completions 接口。模型 ID 不写死，避免模型下线、权限或账户范围变化造成误配。请从当前模型目录复制一个真实可用的模型 ID。

macOS/Linux：curl

export AIHUBMIX_API_KEY='替换为你的真实 Key'
export AIHUBMIX_MODEL_ID='替换为当前可用模型 ID'
curl -i 'https://aihubmix.com/v1/chat/completions' \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$AIHUBMIX_MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"请只回复：连接成功\"}]}"

Windows PowerShell

$env:AIHUBMIX_API_KEY = '替换为你的真实 Key'
$env:AIHUBMIX_MODEL_ID = '替换为当前可用模型 ID'
$body = @{ model = $env:AIHUBMIX_MODEL_ID; messages = @(@{ role = 'user'; content = '请只回复：连接成功' }) } | ConvertTo-Json -Depth 5
curl.exe -i 'https://aihubmix.com/v1/chat/completions' -H "Authorization: Bearer $env:AIHUBMIX_API_KEY" -H 'Content-Type: application/json' --data $body

Python

import os
import requests

api_key = os.environ['AIHUBMIX_API_KEY']
model_id = os.environ['AIHUBMIX_MODEL_ID']

response = requests.post(
    'https://aihubmix.com/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    },
    json={
        'model': model_id,
        'messages': [{'role': 'user', 'content': '请只回复：连接成功'}],
    },
    timeout=60,
)

print('HTTP', response.status_code)
try:
    print(response.json())
except ValueError:
    print(response.text)
response.raise_for_status()

JavaScript：Node.js 服务端

const apiKey = process.env.AIHUBMIX_API_KEY;
const modelId = process.env.AIHUBMIX_MODEL_ID;

const response = await fetch('https://aihubmix.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: modelId,
    messages: [{ role: 'user', content: '请只回复：连接成功' }],
  }),
  signal: AbortSignal.timeout(60000),
});

const text = await response.text();
console.log('HTTP', response.status, text);
if (!response.ok) throw new Error(`API request failed: ${response.status}`);

JavaScript 示例使用 Node.js 原生 fetch 和 AbortSignal.timeout。建议使用支持这两个 API 的较新 Node.js 版本；旧版环境应按自身版本安装兼容的 HTTP 客户端或改用其他超时写法。无论使用哪种语言，都应同时检查 HTTP 状态码和 JSON 响应正文。

看到成功响应且其中包含模型返回内容，才算完成一次有效验证。只打开域名、收到 HTML 页面，或仅请求公共模型列表，都不能证明该 Key 已经具备目标模型的调用权限。

Base URL、接口路径和 aihubmix.cyou 怎么核对

Base URL 与完整接口地址的关系可以写成：Base URL + 接口路径 = 完整请求地址。对于当前公开 Quick Start 的 OpenAI 兼容示例，公式是 https://aihubmix.com/v1 + /chat/completions = https://aihubmix.com/v1/chat/completions。

场景	建议核对方式	不要这样做
OpenAI 兼容 SDK	Base URL 填 `https://aihubmix.com/v1`，由 SDK 生成具体路径	不要再手动拼接一个 `/v1`
手写 curl	直接使用完整地址 `https://aihubmix.com/v1/chat/completions`	不要把网页首页地址当成接口地址
aihubmix.cyou 应用示例	确认是否属于应用合作场景，并按页面要求生成 APP-Code	不要因为示例出现 APP-Code，就认为所有直接 API 调用都必须携带它
多个公开页面地址不一致	以当前协议文档、账户页面和实际请求响应交叉核对	不要在不同客户端中混用多个未确认的 Base URL

aihubmix.cyou 的公开 App Store 页面展示了 https://aihubmix.cyou/v1/chat/completions 和 APP-Code 示例，但公开 Quick Start 明确把 https://aihubmix.com 作为主示例域名。因此，本文不把 aihubmix.cyou 固定写成所有用户都应使用的 API Base URL。若当前账户或应用页面明确给出该地址，再按页面说明使用；否则优先采用当前 Quick Start 中可核验的地址。

Anthropic Messages、Gemini 原生接口与 OpenAI 兼容接口的路径、请求体和认证头可能不同。公开开发者资料显示，OpenAI 兼容接口使用 Bearer 认证，而其他协议可能使用不同请求头。不要只替换域名，就认为三个协议完全兼容。

401、403、404、429 和模型错误怎么排查

现象	先检查什么	下一步
401 Unauthorized	Authorization 头、环境变量、Key 是否完整、过期或已删除	重新读取环境变量，检查是否把 Key 名称误当成 Key 值，确认没有多余空格或引号
403 Forbidden	余额、账户状态、模型权限、IP 白名单和工作区权限	查看错误 JSON 与密钥设置；如果提示余额不足，进入账户余额页面核对
404 或路径错误	Base URL 是否已经包含 `/v1`，接口路径是否重复	先复制 Quick Start 的完整路径做最小请求，再回填 SDK
429 Too Many Requests	请求频率、并发和响应中的 Retry-After	有 Retry-After 就按其等待；没有时使用有限次数的指数退避，不要无限重试
503 或模型不可用	模型 ID 是否准确、当前账户是否有权限、模型渠道是否可用	从当前模型目录重新复制 ID，并查看错误中的 traceId 或 tid
请求超时	客户端超时、输入长度、模型响应时间和网络链路	设置合理 timeout，缩短测试输入，并查看请求日志

公开错误码文档显示，403 可能与余额不足、账户状态、权限或 IP 范围有关；429 通常表示请求频率超过限制；部分 503 响应可能与模型 ID、模型权限或上游限流有关。排查时不要只看状态码，还要读取错误 JSON 和 traceId。若请求结果不明确，不要立刻无限重放生成请求，因为原请求可能已经产生用量。

密钥只显示一次、泄露或需要轮换怎么办

刚创建：在创建窗口关闭前复制完整 Key，写入环境变量或密钥管理器。
忘记 Key：不要从网页源码、日志或聊天记录中恢复；如果已经无法查看，就重新创建。
怀疑泄露：先在 API keys 页面删除或停用旧 Key，再检查用量和请求日志。
正常轮换：先创建新 Key，更新服务端变量并完成一次真实请求，确认新 Key 成功后再删除旧 Key。
怀疑重复扣费：先查看原请求状态、请求日志和交易记录，再决定是否重试。

公开隐私政策说明，API Key 创建时只显示一次，删除后使用该 Key 的 API 调用会停止。具体菜单名称可能因账户或工作区变化，实际操作以当前控制台显示为准。不要把完整 Key 发给客服；公开联系页面也建议提交问题时提供时间、模型、端点、HTTP 状态和 trace ID，但删除密钥、密码和支付信息。

费用与最低充值金额如何理解

API Key 不是价格，也不代表所有模型都免费。实际费用应查看当前模型目录、账户余额和计费页面；免费模型、试用额度、请求限制、模型价格和并发规则都可能变化，本文不把旧页面中的数字当成长期配置。

截至 2026年10月27日检索到的公开计费文档，账户充值通过 Stripe 完成，单次充值最低为 15 美元，并要求使用整美元金额。这里的 15 美元是单次充值最低金额，不是 API Key 价格、账户最低余额，也不是每次 API 调用的起步费用；支付方式、账户规则和实际余额仍以当前控制台显示为准。可查看 Balance and billing。

常见问题

AIHubMix API Key 在哪里获取？

登录账户后进入控制台的 API keys 页面创建。公开隐私政策列出的控制台地址是 <code>https://console.aihubmix.com/</code>；如果菜单或入口发生变化，可从 Quick Start 页面进入。

AIHubMix API Key 是不是只显示一次？

是。公开隐私政策和密钥管理文档都说明，创建窗口可能只显示完整 Key 一次。关闭窗口后不要假设还能查看原值；遗失时应重新创建，并在新请求成功后停用旧 Key。

AIHubMix 的 Base URL 应该怎么填？

当前公开 Quick Start 的 OpenAI 兼容示例使用 <code>https://aihubmix.com/v1</code>，完整 Chat Completions 地址是 <code>https://aihubmix.com/v1/chat/completions</code>。如果 SDK 的 Base URL 已含 <code>/v1</code>，不要再次拼接。

aihubmix.cyou 能不能直接当作 API Base URL？

不能仅凭 App Store 页面示例就下定论。该页面展示了带 APP-Code 的 <code>aihubmix.cyou/v1/chat/completions</code> 示例，但公开 Quick Start 使用 <code>aihubmix.com</code> 作为主示例域名。请以当前账户、具体应用文档和协议页面给出的地址为准。

为什么 API Key 正确却返回 401 或 403？

401 先检查 Authorization 头、环境变量、Key 是否过期或已删除；403 还要检查余额、账户状态、模型权限、IP 白名单和工作区权限。读取错误 JSON、traceId 和请求日志，通常比反复重试更容易定位。

调用 AIHubMix 时必须填写 APP-Code 吗？

不一定。APP-Code 主要出现在部分应用接入或合作场景中。直接 API 调用是否需要它，应看具体应用或协议文档；如果当前接口没有明确要求，不要把 APP-Code 当成 API Key。

怎么判断 API Key 真的可用？

使用当前模型目录中的已授权模型 ID，向 <code>https://aihubmix.com/v1/chat/completions</code> 发起一次最小请求，并同时检查 HTTP 状态码和 JSON 响应。成功返回模型内容，才算完成有效验证。

15 美元是 API Key 的价格吗？

不是。公开计费文档显示，15 美元是通过 Stripe 充值时的单次最低充值金额，并要求使用整美元；它不代表 API Key 价格、最低余额或单次调用费用，实际规则以当前账户页面为准。

参考资料

AIHubMix Quick Start：Generate an API key and make your first call（aihubmix.mintlify.app）
AIHubMix API key management（aihubmix.mintlify.app）
AIHubMix Privacy Policy：API Keys and Access Management（preview.aihubmix.com）
AIHubMix HTTP Status Codes Overview（aihubmix.mintlify.app）
AIHubMix Balance and billing（aihubmix.mintlify.app）
AIHubMix App Store：APP-Code and API example