在 CodexBar 中接入 ElevenLabs Provider：API Key 配置、订阅用量解析与错误排查实战指南

在 CodexBar 中接入 ElevenLabs ProviderAPI Key 配置、订阅用量解析与错误排查实战指南【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBarElevenLabs 是 CodexBar 内置的用量统计 Provider 之一它通过官方订阅接口按 API Key 读取当前计费周期内的字符额度、剩余字符数、重置时间与音色槽位用量无需任何浏览器登录流程。本篇指南以 docs/elevenlabs.md 为核心骨架结合仓库内 ElevenLabs Provider 的完整源码实现与测试用例系统讲解其功能边界、三种配置方式、底层 API 解析逻辑与全部错误场景的定位方法读完即可在菜单栏中正确展示 ElevenLabs 额度并独立排障。功能总览ElevenLabs Provider 能展示什么ElevenLabs Provider 的数据来源是官方订阅接口面向 API Key 鉴权场景主要提供以下能力字符信用额度Character credits展示当前订阅周期内已使用字符数与总限额重置时间当接口返回next_character_count_reset_unix时将其换算为本地重置时间并用于何时回满额度的提示音色槽位用量当响应中存在voice_slots_used/voice_limit与professional_voice_slots_used/professional_voice_limit时分别展示普通音色与专业音色槽位的占用情况套餐与状态文本从订阅响应中解析tier套餐档位与status订阅状态用于菜单栏的登录方式与套餐标签显示。值得注意的两个设计点其一该 Provider不支持费用历史与 Token 成本统计其令牌成本配置中的提示文案明确写着ElevenLabs cost history is not available via API yet见 ElevenLabsProviderDescriptor.swift其二它默认不启用defaultEnabled: false需要用户显式配置并开启。工作原理订阅接口的请求与字段映射请求规格Provider 的核心请求封装在 ElevenLabsUsageFetcher.swift 中端点GET https://api.elevenlabs.io/v1/user/subscription鉴权头xi-api-key: key同时设置Accept: application/json超时15 秒timeoutSeconds 15测试中亦有对应断言Key 预处理请求前会对 API Key 做空白字符 trim空白 Key 直接抛出missingCredentials不会发出网络请求响应字段映射响应体通过ElevenLabsSubscriptionResponse解码snake_case 与 Swift 驼峰命名通过CodingKeys映射完整字段如下接口字段内部属性说明character_countcharacterCount当前周期已使用字符数character_limitcharacterLimit当前周期字符总额度voice_slots_usedvoiceSlotsUsed已占用普通音色槽位可选voice_limitvoiceLimit普通音色槽位上限可选professional_voice_slots_usedprofessionalVoiceSlotsUsed已占用专业音色槽位可选professional_voice_limitprofessionalVoiceLimit专业音色槽位上限可选current_overagecurrentOverage当前超额信息{amount, currency}可选tiertier套餐档位可选statusstatus订阅状态可选next_character_count_reset_unixnextCharacterCountResetUnix下次字符额度重置的 Unix 时间戳可选解码成功后parseSnapshot将next_character_count_reset_unix转换为Date存入resetsAt供菜单栏的刷新倒计时使用。用量与展示计算ElevenLabsUsageSnapshot提供三个关键派生值均有测试覆盖见 ElevenLabsUsageFetcherTests.swiftusedPercentcharacter_count / character_limit经UsagePercent的displayClamped处理后的显示百分比额度为 0 时返回 0remainingCharactersmax(0, character_limit - character_count)即剩余字符数toUsageSnapshot()将快照映射为通用UsageSnapshot。其中主用量窗口的 reset 描述格式为25,000 / 100,000 credits数字带千分位分组当音色槽位字段存在且 limit 大于 0 时会额外生成voice-slotsVoice slots与professional-voicesProfessional voices两个命名窗口作为extraRateWindows叠加展示。套餐标签的展示逻辑也有讲究tier中的下划线会被替换为空格并首字母大写如creator显示为Creator当status存在且不为active时会追加 · status后缀若tier为空则直接回退显示status。此外ElevenLabsProviderDescriptor.swift 中还维护了一套套餐档位到本地化标签的映射表free / starter / creator / pro / scale / business / growing business / enterprise分别对应Free / Starter / Creator / Pro / Scale / Business / Business / Enterprise。端点覆盖与 URL 拼装请求默认打到https://api.elevenlabs.io但支持通过ELEVENLABS_API_URL覆盖详见下文环境变量。URL 拼装逻辑在subscriptionURL(baseURL:)中若基础 URL 路径以/v1结尾则直接追加user/subscription否则追加v1/user/subscription。因此https://elevenlabs.test与https://elevenlabs.test/v1/两种写法都能正确得到/v1/user/subscription这一点同样有测试专门验证fetch usage accepts versioned API base with trailing slash。配置方式三种途径与多 Key 账户方式一CLI 快速写入推荐无需打开设置界面一条命令即可把 Key 写入本地配置printf %s $ELEVENLABS_API_KEY | codexbar config set-api-key --provider elevenlabs --stdin该命令会trim 管道传入的 Key → 以受限文件权限写入~/.codexbar/config.json→ 默认启用 ElevenLabs Provider。如果只想保存 Key 而不启用 Provider追加--no-enable参数即可。这一能力由 CLIConfigCommand.swift 提供。方式二设置界面打开Settings - Providers启用ElevenLabs在 ElevenLabs 控制台的API Keys设置页创建或复制一个 API Key将 Key 粘贴到 CodexBar 的 ElevenLabs Provider 设置项中。对应设置字段由 ElevenLabsProviderImplementation.swift 描述这是一个 secure 类型的 API key 字段占位符为xi-...存储位置同样是~/.codexbar/config.json。Provider 的可用性判定也很明确只要环境变量中存在 Key、配置中已填写 Key、或已配置至少一个 ElevenLabs 令牌账户Provider 即视为可用。方式三环境变量CodexBar 依次读取以下环境变量第一个非空值生效且值会被 trim支持去掉成对的引号包裹变量用途ELEVENLABS_API_KEY主 API KeyXI_API_KEYElevenLabs 官方兼容别名兼容旧脚本/旧环境ELEVENLABS_API_URL覆盖 API 基础地址用于测试或自托管/代理场景环境变量的解析与校验集中在 ElevenLabsSettingsReader.swift。需要特别说明ELEVENLABS_API_URL的安全约束该值必须通过ProviderEndpointOverrideValidator.normalizedHTTPSURL的校验即 HTTPS URL 或裸主机名否则会抛出invalidEndpointOverride错误提示ElevenLabs endpoint override must use HTTPS or a bare host。这一校验同样适用于其他 Provider防止配置被篡改为非 HTTPS 端点。多 Key 令牌账户除上述单一 Key 之外ElevenLabs Provider 还支持令牌账户Token Account在 ElevenLabsProviderDescriptor.swift 的凭据适配器中令牌账户被描述为Store multiple ElevenLabs API keys占位符为Paste API key…以环境注入方式ELEVENLABS_API_KEY向请求解析器提供当前激活账户的 Key。这意味着你可以维护多个 ElevenLabs Key 账户并随时切换故障排查中提到的活跃账户优先于独立 API Key 字段正是这一机制的表现。状态码处理与错误分类机制fetchUsage对 HTTP 状态码的分流非常清晰200解析订阅响应401调用authenticationError(responseData:)默认归类为authenticationFailed403调用authenticationError(responseData:fallback: .accessDenied)默认归类为accessDenied其余状态码记录日志并抛出通用apiError(HTTP code)。authenticationError会先尝试从响应体中解码detail对象然后依次优先读取detail.code再读取旧的detail.status字段——因为线上响应可能用通用 code 搭配更具体的 legacy status。两个字段任一命中以下值即完成归类均先 trim 再转小写匹配识别值code 或 status归类错误触发状态码invalid_api_keyinvalidCredentials401missing_permissions/insufficient_permissionsmissingPermissions401 / 403其他未知值authenticationFailed401或accessDenied403401 / 403一个值得强调的安全细节错误消息如message字段中的敏感内容不会被复制进诊断输出。测试current and legacy error details preserve safe diagnostics专门验证了包含sensitive-response-marker的原始消息绝不会出现在errorDescription中。故障排查全部错误场景速查Missing ElevenLabs API keyKey 未配置。按上面任一方式补齐即可使用codexbar config set-api-key --provider elevenlabs --stdin、在Settings - Providers - ElevenLabs中粘贴 Key、设置ELEVENLABS_API_KEY环境变量或配置一个 ElevenLabs 令牌账户。对应源码中的missingCredentials其错误描述会提示在~/.codexbar/config.json的apiKey字段或ELEVENLABS_API_KEY中设置。ElevenLabs rejected the selected API key接口返回了识别为invalid_api_key的认证/访问错误。请确认 Key 有效且未被吊销若配置了多个 ElevenLabs API-Key 账户注意当前激活账户优先于独立的 API Key 字段应检查激活账户所用的 Key。ElevenLabs API key is missing the user_read permission接口返回 HTTP 401/403且错误标识为missing_permissions或insufficient_permissions。请为所选 Key 开启user_read权限——CodexBar 需要该权限才能获取订阅用量。ElevenLabs could not authenticate the selected API key接口返回 HTTP 401 且错误中未识别出已知的 code/status。检查 Key 本身及该 Key 的端点权限。ElevenLabs denied access for the selected API key接口返回 HTTP 403 且未识别出明确的 Key 或权限错误。检查该 Key 的端点权限以及 ElevenLabs API-Key 设置中的IP 白名单IP allowlist——请求来源 IP 被拒通常表现为这一场景。ElevenLabs API error非 2xx 且非 401/403 的通用错误例如 HTTP 500。确认当前网络可以访问api.elevenlabs.io并核对报告的具体 HTTP 状态码。关于错误判定的整体规则CodexBar 优先读取响应中已识别的detail.code值其次读取旧版detail.status当 code 缺失或过于泛化时线上响应仍可能用该字段表达具体拒绝原因具体实现见 ElevenLabsUsageFetcher.swift 的authenticationError方法Provider 错误消息不会原样进入诊断输出。源码级验证测试如何保证解析正确ElevenLabs Provider 的解析与错误逻辑在 ElevenLabsUsageFetcherTests.swift 中有系统性覆盖主要验证点包括完整响应解析一份包含全部字段的样例响应tier: creator、25,000/100,000 字符、2/10 普通音色、1/2 专业音色、current_overage、next_character_count_reset_unix应得到 25% 用量、75,000 剩余字符、25,000 / 100,000 credits的 reset 描述、Creator登录标签与 2 个附加音色窗口请求头正确性xi-api-key头、/v1/user/subscription路径与 15 秒超时均有断言错误分类矩阵13 组 401/403 与不同detail形态code 优先、status 兜底、大小写与空白容忍、空 detail、非 JSON、非对象 detail 等逐一映射到正确的错误类型安全约束敏感响应内容不会泄漏到错误描述中空 Key 拦截纯空白 Key 在发请求前即被拒绝。此外ElevenLabsUsageSnapshotLinuxTests.swift 提供了 Linux 侧的用量快照测试印证该 Provider 的解析逻辑在跨平台macOS/Linux测试链路中保持一致。小结ElevenLabs Provider 是 CodexBar 众多 Provider 中典型的纯 API Key 订阅接口范式无浏览器 Cookie、无登录态数据面只有字符额度、音色槽位与套餐状态三类信息但通过完善的字段映射、额度百分比/剩余量计算、tier标签本地化、多 Key 令牌账户与精细的错误分类足以在菜单栏中提供可靠的 ElevenLabs 用量监控。配置侧CLI 管道写入、设置界面与环境变量三选一即可完成接入排障侧五类具体错误消息配合 code/status 双字段识别机制能让绝大多数认证与权限问题在几十秒内定位。如果你正自托管或通过代理访问 ElevenLabs APIELEVENLABS_API_URL配合 HTTPS 校验的覆盖机制同样为你预留了完整的接入路径。更多 Provider 横向对比可参考 docs/providers.md。【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考