本页参考 New API 官方 AI 应用文档，已按青云 TOP API（New API 兼容）环境整理。API 地址使用 https://top.qingyuntop.ai/v1，API Key 使用 $QINGYUN_TOP_API_KEY 占位符，请在青云 TOP API 控制台创建并妥善保存密钥。

LunaTranslator 教程 — 开源 GalGame / 视觉小说翻译器，支持 HOOK、OCR 与 AI 翻译引擎。对接 青云 TOP API 提升翻译质量。

聊天设置选项

在 青云 TOP API 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 LunaTranslator：

{ "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" }

LunaTranslator 是一款开源免费的视觉小说（GalGame）翻译器，致力于提供母语级别的视觉小说游玩体验。

功能支持

  • HOOK 主要使用HOOK提取游戏文本，几乎适配了所有的常见和冷门的视觉小说
  • 内嵌翻译 部分游戏还可以直接内嵌翻译到游戏中，以获取沉浸式体验
  • HOOK模拟器 对NS/PSP/PSV/PS2上的大部分游戏，支持HOOK模拟器直接读取游戏文本
  • OCR 内置较高精度的OCR模型，并支持许多其他在线&离线OCR引擎，以便灵活的读取任意文本
  • 丰富的翻译接口 支持几乎所有翻译引擎，包括大语言模型翻译、离线翻译等
  • 语言学习 支持日语分词及假名注音，支持AnkiConnect，支持Yomitan插件
  • 语音合成 支持大量在线&离线语音合成引擎
  • 语音识别 在Windows 10和Windows 11上，可以使用Windows语音识别。

安装方式

在 LunaTranslator 文档- 下载 & 启动 & 更新 进行下载安装

在 LunaTranslator 接入 青云 TOP API

LunaTranslator 支持接入本地部署的 青云 TOP API。请使用您自己部署的 青云 TOP API，或确认服务方具备合法上游授权和合规义务的 青云 TOP API 服务。不要将来源不明的 API 地址或密钥接入生产环境。

一键配置

  1. 在 青云 TOP API 控制台的系统设置\->聊天设置中，添加如下快捷选项：

`` { "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" } ``

!add\_config

  1. 在 `青云 TOP API` -> 控制台 -> 令牌管理 选项卡中选择要使用在 LunaTranslator 的令牌，点击聊天按钮旁的下拉选项，选择 LunaTranslator,将会跳转到 LunaTranslator 并自动配置 API 地址与 API Key

!跳转到 LunaTranslator

  1. 在 `LunaTranslator` -> 设置 -> 翻译设置 -> 大模型 中将出现一个新增的大模型接口配置，点击编辑

!设置api

  1. 点击 model 下拉框旁的刷新按钮，获取 青云 TOP API 平台的模型列表，选择或输入模型名称，完成后点击确定保存

!设置模型

  1. 检查 new\_api 大模型接口配置旁边的开关按钮是否打开，若未启用则启用接口即可开始使用

!开启配置

手动配置

  1. 在 `青云 TOP API` -> 控制台 -> 令牌管理 选项卡中获取 API Key

!获取 API Key

  1. 在 `LunaTranslator` -> 设置 - 翻译设置 -> 大模型 中选择添加

!添加 API

  1. 复制 大模型通用接口 模板，新增接口

!添加 API2

  1. 在 新增的接口 中，填写对应的 API 地址和 API Key

!设置 API1

!设置 API2

  1. 点击 model 下拉框旁的刷新按钮，获取 青云 TOP API 平台的模型列表，选择或输入模型名称，完成后点击确定保存

!设置 API3

  1. 点击 青云 TOP API 旁边的开关按钮，启用接口即可开始使用

!打开API

更多使用方式请查看 LunaTranslator 官方文档:LunaTranslator 文档 - 大模型翻译接口

接入检查

  • API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
  • API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
  • 模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。