接入YouVersion新API的4个坑，我们踩过了

今年4月，YouVersion开放了平台API。我们给开源圣经学习系统Equip加了个"每日经文"卡片，结果发现文档没写的细节比想象的多。四个小坑，记录一下。

Equip是个FastAPI+React+Supabase的开源LMS，MIT协议。仪表盘上的每日经文是个安静但关键的功能——给页面右侧一个牧养锚点，同时让左侧保持行动导向，培养每日回访习惯而不强求互动。

YouVersion Platform的数据很全：1,474种圣经译本，1,283种语言，REST API加SDK（Swift、Kotlin、React、React Native），非商用免费。我们接入了。

端点设计很简洁。摩擦藏在细节里。

坑一：/v1/bibles 不带 language_ranges[] 直接422

装好httpx后的本能写法：

# 错的，跑不通
httpx.get("https://api.youversion.com/v1/bibles",
headers={"X-YVP-App-Key": KEY})

返回：

HTTP 422 Unprocessable Entity
{"detail": [{"type": "missing",
"loc": ["query", "language_ranges[]"],
"msg": "Field required"}]}

列表端点至少需要一个ISO 639-3语言过滤器。我们跟所有人一样——从422响应体里读出来的。正确写法：

httpx.get(
"https://api.youversion.com/v1/bibles",
params={"language_ranges[]": "eng"}, # eng、rus、ukr等
headers={"X-YVP-App-Key": KEY},
)

如果用JS客户端调URLSearchParams，括号很重要——带字面量方括号的 language_ranges[] 能工作，去掉括号的 language_ranges 不行。

顺便：认证头是 X-YVP-App-Key，不是 Authorization: Bearer。忘了这个拿到的401提示很通用，你会对着密钥逐个字符检查半天才回头翻文档。集成第一天就把这个头名钉在docstring里。

坑二：all_available=true 才能看到真目录

用 language_ranges[]=eng,rus,ukr 调用，返回11种译本——全是英语（ASV、BSB、Geneva、CPDV等）。零俄语。零乌克兰语。

宣传数字是1,474种译本。其他的在哪？

httpx.get(
"https://api.youversion.com/v1/bibles",
params={"language_ranges[]": "rus", "all_available": "true"},
headers={"X-YVP-App-Key": KEY},
)

这样返回5种俄语圣经：NRT（Новый Русский Перевод，我们需要的现代俄语）、三个CARS变体、CSLAV（教会斯拉夫语）。乌克兰语只有UKRK 1905——革命前版本，现代学生读起来费劲。现代Огієнко或UBIO译本平台还没有。

心智模型：不带 all_available 的列表端点显示的是你的应用密钥已启用的内容，不是平台存在的全部。用 /bibles/{id}/passages/{ref} 获取经文对更广泛的目录是有效的——至少目前非商用如此。花两分钟用自己的密钥验证一下，免得UI上显示"无俄语译本"时尴尬。

坑三：passage.content 是原始USFM，不是渲染文本

获取经文：

httpx.get(
f"https://api.youversion.com/v1/bibles/{bible_id}/passages/{ref}",
headers={"X-YVP-App-Key": KEY},
)

返回的 passage.content 是原始USFM标记：\v 1、\p、\add 等。不是纯文本，不是HTML。

我们用了 usfm-grammar（MIT，WebAssembly加速）做客户端解析。轻量方案：如果只需要纯文本，正则 strip \[\w+\*?\] 能走80%的路，但脚注和交叉引用会乱。USFM是标准，但"标准"意味着你要自己处理渲染管线。

坑四：verse-of-the-day 端点有隐藏的分发逻辑

/v1/verse-of-the-day 存在，但行为跟直觉不同。它返回的是YouVersion全局当日经文，不是你指定的圣经版本。想给俄语用户显示俄语每日经文？端点不支持按语言或译本过滤。

我们的解法：自己维护一个经文日历表，用 /passages 端点拉取。多一步，但可控。如果你依赖官方每日经文做多语言产品，这里需要架构决策。

干净的实现

最终我们的仪表盘卡片长这样：左侧是课程进度和待办，右侧窄栏放当日经文。USFM解析后纯文本显示，带译本缩写和章节链接。加载<200ms，缓存24小时。

代码在 Equip 仓库的 apps/web/app/components/VerseOfDay.tsx 和 apps/api/app/routers/youversion.py。MIT协议，直接拿。

YouVersion Platform API 是扎实的工程：数据深、端点干净、非商用免费。只是这四个小地方——语言过滤必填、all_available 开关、USFM原始格式、每日经文不可定制——文档没强调，我们花了时间摸索。写在这里，省你半天。