新乌托邦 · 居民接入指南 (官方文档)

🌱 第一步：获取您的专属密钥 (API Key)

1 登录新乌托邦主站后，点击左侧导航菜单的【API密钥】（或 API Keys），然后点击左上角的 【添加令牌】 按钮。
2 名称可以随意填写（例如：我的酒馆专用）；额度强烈建议勾选【无限额度】（默认勾选，请放心，它只是一个限额开关，实际消耗依然从您的账户总余额中扣除）。
3 ⚠️ 避坑重点：弹窗中的 【模型限制】 与 【IP 限制】 请务必保持留空，绝对不要勾选，否则会导致客户端无法调用！【分组】按您的需求选择即可（默认选用户分组）。
4 点击提交后，在令牌列表中找到刚刚创建的密钥，点击【复制】，即可获得一串以 sk- 开头的密钥。

🧭 第二步：理解接口地址（⚠️ 90% 的报错都是因为这里！）

由于不同的客户端软件在底层拼接网址的逻辑不同，填入的格式会有 加不加 /v1 的区别。如果遇到连接失败或报错 404，请按以下三种格式依次尝试：

🍃 格式 A：带 /v1 结尾（SillyTavern 酒馆必填 / 最常用）

https://api.xwtb.world/v1

🍵 格式 B：基础域名，不带 /v1（NextChat / ChatBox 等日常软件用）

https://api.xwtb.world

🍂 格式 C：完整对话路径（极少数老旧插件或特殊软件要求时使用）

https://api.xwtb.world/v1/chat/completions

🍻 第三步：常见客户端配置教程

🏰 1. SillyTavern (酒馆) 配置方法【强烈推荐】

无论您使用的是电脑本地酒馆、手机 Termux 酒馆还是云酒馆，配置步骤完全一致：

1打开酒馆网页，点击顶部菜单栏的 【插头图标 🔌】 (API Connections)。
2API (接口类型)：在下拉框中选择 Chat Completion (聊天补全)。
3Chat Completion Source (聊天补全来源)：选择 Custom (OpenAI-compatible) (自定义 OpenAI 兼容)。
4Custom Endpoint (自定义端点 / 反代地址)：
请填入格式 A 👉 https://api.xwtb.world/v1 （注意：酒馆这里后面必须带 /v1，且末尾不要多打斜杠 /）。
5Custom API Key (自定义密钥)：粘贴您第一步复制的 sk-xxxxxx 密钥。
6点击下方的 【Connect / 连接】 按钮。当亮起绿灯表示连接成功后，在 Available Models (可用模型) 下拉框中即可选择您想玩的模型！（若列表未刷新，可勾选手动输入本站【定价】页里的模型名称）。

🎮 2. RisuAI / PR / 小白盒等角色扮演软件

1进入软件的【设置】 -> 【模型/机器人设置 (Bot Settings)】。
2AI 提供商选择 OpenAI 或 Custom (自定义)。
3反向代理 URL (Reverse Proxy)：观察输入框的灰色提示文字，如果它提示需要填 .../v1/chat/completions，请复制上面的 格式 C 填入；如果只要求填 Base URL，请复制 格式 A (带 /v1) 填入。
4填入 sk- 密钥，选择或手动输入本站支持的模型名称即可。

💬 3. 日常聊天软件 (Cherry Studio / NextChat / ChatBox / LobeChat)

1打开软件的【设置】 -> 【模型服务商】 -> 选择 OpenAI。
2API 域名 / 接口地址：通常填入 格式 B（https://api.xwtb.world），因为这类软件底层会自动帮您补全 /v1（如果测试报错，再尝试手动加上 /v1）。
3填入 sk- 密钥，并在模型列表中手动添加本站【定价】页面支持的模型名称即可。

💻 开发者代码调用示例 (Python SDK)

如果您是开发者，想要在自己的项目或脚本中接入新乌托邦，只需使用 OpenAI 官方 SDK 并将 base_url 替换为本站地址即可：

from openai import OpenAI

client = OpenAI(

    # 1. 填入您在【令牌】页面获取的 sk- 密钥

    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

    # 2. 官方 SDK 此处必须包含 /v1

    base_url="https://api.xwtb.world/v1"

)

response = client.chat.completions.create(

    model="gpt-4o-mini",  # 请替换为本站【定价】页面实际支持的模型名称

    messages=[

        {"role": "system", "content": "你是一个温柔的新乌托邦向导。"},

        {"role": "user", "content": "你好呀！"}

    ],

    temperature=0.7

)

print(response.choices[0].message.content)

🚑 常见报错与自救指南 (FAQ)

Q1：报错 401 Unauthorized 或提示 “无效的令牌”？

原因与解决：API Key 填错了，或者复制时不小心多带了空格。请回到本站【令牌】页面重新点击复制，并确认您的账户【钱包】内是否有可用余额。

Q2：报错 404 Not Found 或一直转圈连不上？

原因与解决：100% 是因为接口地址（URL）格式没填对！请先检查网址开头是不是 https://（不能是 http），然后参考【第二步】，尝试在网址末尾加上 /v1 或者去掉 /v1。

Q3：报错 “当前分组 xxx 下对于模型 xxx 无可用渠道”？

原因与解决：① 模型名字拼写错误（注意大小写，前后不能有空格），建议直接去本站左侧【定价】页面点击模型名称复制；② 您创建【令牌】时选择的“分组”不对，请修改令牌分组与模型所在分组一致。

Q4：报错 429 Too Many Requests 或提示 “额度不足”？

原因与解决：您的账户总余额已用尽，或令牌设置了过小的限额。请前往首页公告中的【能量补给站】购买兑换码，并在【钱包】页面进行充值。

🏡 新乌托邦 · 居民接入指南

🌱 第一步：获取您的专属密钥 (API Key)

🧭 第二步：理解接口地址（⚠️ 90% 的报错都是因为这里！）

🍻 第三步：常见客户端配置教程

💻 开发者代码调用示例 (Python SDK)

🚑 常见报错与自救指南 (FAQ)