transistor

transistor — 通过终端托管 Transistor.fm 播客

通过其 v1 JSON:API 操作 Transistor.fm 账户：节目、剧集、从草稿到发布的生命周期、每日下载分析、私密播客订阅者和 Webhook。响应为 JSON:API 文档；捆绑的 CLI 会解包这些文档（--json），同时保留 Agent 使用 jq 所需的原始结构。写入命令均设有保护：创建剧集始终会创建草稿，发布则通过专用端点进行。

设置

1. 在 Transistor 控制面板的 Account page → API Access（https://dashboard.transistor.fm/account）中找到 API 密钥并导出：

export TRANSISTOR_API_KEY="<API_KEY>"

2. 验证密钥（GET /v1 — 授权探测；没有 /v1/user 路由）：

transistor user          # name and time zone
transistor user --json | jq '{id, name, time_zone}'

每个播客的密钥权限与其用户的控制面板角色（所有者 / 管理员 / 团队成员）一致。无需凭据即可使用 --help 和 --dry-run。请求限制为每 10 秒 10 次；遇到 429 时，CLI 会给出明确提示并退出，而不是继续发送大量请求。

核心命令

user — 授权探测

transistor user                # who does this key belong to?
transistor user --json

shows / show — 浏览播客

transistor shows                          # newest-updated first
transistor shows --private --json         # private podcasts only
transistor show --id <SHOW_ID_OR_SLUG>    # full attributes incl. feed_url
transistor shows --page 1 --per 20 --json

在大多数节目级路由中，节目 ID 和 slug 可以互换。节目资源不包含计数字段 — 使用 episodes --show ... --json 查询，再查看 meta.totalCount。

episodes / episode — 浏览剧集

transistor episodes                                    # newest first, all shows
transistor episodes --show <SHOW_ID> --status draft    # drafts for one show
transistor episodes --show <SHOW_ID> --per 50 --page 1 --json
transistor episode --id <EPISODE_ID> --include show    # compound doc + parent show

--include show 会添加 included[]（JSON:API 复合文档）；--json 输出中的每个剧集条目都已从关系中解析出 show_id。对于旧脚本，--limit 可作为 --per 的别名。

episode-create / episode-update — 草稿和元数据

transistor episode-create --show <SHOW_ID> --title "Ep 12: Roasting" \
  --season 2 --number 4 --audio-url "https://uploads.example.com/ep12.mp3"
transistor episode-update --id <EPISODE_ID> --title "New title"
transistor episode-update --id <EPISODE_ID> --audio-url "<AUDIO_URL>"   # attach audio

episode-create 始终会创建草稿（status: "draft"、 published_at: null）— 从不发布。episode-update 会更改元数据或附加音频，不会更改发布状态。

episode-publish — 生命周期切换

transistor episode-publish --id <EPISODE_ID>                       # publish now
transistor episode-publish --id <EPISODE_ID> --status scheduled \
  --published-at "2026-09-03 09:00:00"                             # schedule
transistor episode-publish --id <EPISODE_ID> --status draft        # unpublish

调用 PATCH /v1/episodes/<EPISODE_ID>/publish，并设置 episode[status]=draft|scheduled|published — 这是文档中说明的专用端点。如果剧集的 media_url 仍为空，CLI 会拒绝发布（无法播放的条目会出现在每位订阅者的订阅源中）；传入 --force 可强制执行。

authorize-upload — 本地音频（最大 5GB）

transistor authorize-upload --filename ep12.mp3                 # plan only
transistor authorize-upload --filename ep12.mp3 --file ./ep12.mp3

返回签名 PUT 请求（使用 --file 时会执行该请求）；打印出的 audio_url 可通过 episode-create / episode-update 附加。签名 URL 会过期（文档示例中约为 600 s）。

analytics / episode-analytics — 每日下载量

transistor analytics --show <SHOW_ID>                        # last 14 days
transistor analytics --show <SHOW_ID> \
  --start-date 01-08-2026 --end-date 28-08-2026 --json
transistor episode-analytics --id <EPISODE_ID> --json

日期格式为 dd-mm-yyyy，且必须成对提供。分析属性是按日排列的 downloads[] 数组，而非总数；CLI 会将其求和为 downloads_total，并保留原始数组。

subscribers — 私密播客受众

transistor subscribers --show <SHOW_ID> --json
transistor subscriber-create --show <SHOW_ID> --email "[email protected]"
transistor subscriber-batch --show <SHOW_ID> --email "[email protected]" --email "[email protected]"
transistor subscriber-delete --show <SHOW_ID> --email "[email protected]"   # or --id

webhooks — 推送，而非轮询

transistor webhooks --show <SHOW_ID>
transistor webhook-create --show <SHOW_ID> --event episode_published \
  --url "https://example.com/hooks/transistor"
transistor webhook-delete --id <WEBHOOK_ID>

事件：episode_created、episode_published、subscriber_created、 subscriber_deleted。上限：每个账户 50 个。请求限制为每 10 秒 10 次，Webhook 比轮询更及时。

全局标志

transistor --json shows                        # flags work in any position
transistor --dry-run episodes --show <SHOW_ID> # request plan, zero network
transistor --force episode-publish --id <EPISODE_ID>   # skip the audio guard
transistor --quiet shows                       # suppress non-essential output
transistor --verbose episodes                  # detailed stderr logging

--dry-run 会输出 {"dry_run": true, "method", "path", "params"}（写入命令还会添加即将发送的完整 body — 包括方括号键），这样你可以在调用 API 前验证计划。--help 和 --dry-run 无需凭据。

工作流示例

创建、附加音频并发布（核心工作流）

export TRANSISTOR_API_KEY="<API_KEY>"
SHOW=$(transistor shows --json | jq -r '.shows[0].id')          # string id
AUDIO=$(transistor authorize-upload --filename ep12.mp3 --file ./ep12.mp3 --json | jq -r '.audio_url')
EP=$(transistor episode-create --show "$SHOW" --title "Ep 12" \
     --audio-url "$AUDIO" --json | jq -r '.id')                 # draft id
transistor episode-publish --id "$EP"                           # dedicated endpoint
transistor episode --id "$EP" --json | jq '{status, media_url, published_at}'

每个阶段的输出都会传给下一阶段：shows → 字符串 id， authorize-upload → 字符串 audio_url，episode-create → 字符串草稿 id，episode-publish → 最终 status。如果音频已有公开 URL，可跳过第 2 阶段（直接传给 episode-create）。

草稿排查：哪些内容尚未发布？

transistor episodes --show <SHOW_ID> --status draft --json \
  | jq -r '.episodes[] | [.id, .title, (if .media_url == "" then "no-audio" else "ready" end)] | @tsv'
# publish the ready ones (rate limit: 10 req / 10 s — add sleep 1 between calls)

每周下载报告

transistor shows --json | jq -r '.shows[].id' | while read -r S; do
  transistor analytics --show "$S" --json \
    | jq -r --arg id "$S" '[$id, (.downloads_total|tostring)] | @tsv'
  sleep 1
done

JSON 和 jq

--json 的键是对 JSON:API 文档的稳定 snake_case 封装： shows/episodes/subscribers/webhooks（附带 meta 的数组）， 单个资源使用扁平对象，计划则包含 dry_run/method/path/params/body。 属性沿用 Transistor 自身的名称——status、season、 number、duration（秒）、media_url、share_url、published_at、 feed_url——因此 jq 选择器可直接用于针对 api.transistor.fm 的原始 curl 请求。集合分页信息显示为 meta.currentPage/meta.totalPages/meta.totalCount。示例： transistor episodes --show <SHOW_ID> --json | jq -r '.episodes[] | [.id, .title, .status] | @tsv'。对于复合文档，CLI 会解析 关联关系（show_id），并在人类可读模式下打印 included 中的节目摘要；使用原始 curl 时， 按 type 匹配 included[]，并匹配 relationships.show.data.id。

已知注意事项

• 发布是独立端点，绝不会作为副作用发生 — POST /episodes 和 PATCH /episodes/:id 无法更改 status。如果单集 仍是草稿，缺少的步骤是调用 PATCH /v1/episodes/<ID>/publish，并设置 episode[status]=published。（加厚前的 CLI 根本没有发布路径。）
• 用户探测端点是 GET /v1 — /v1/user 和 /v1/authorization 会返回 404，且用户资源没有 email 属性（仅有 name 和 time_zone）。
• 分页使用 pagination[page] + pagination[per]（默认值为 0 和 10；文档示例请求第 1 页）。pagination[limit] 和 page[number] 会被静默忽略——使用它们的循环会永远重复读取第 1 页。 循环条件为 meta.currentPage < meta.totalPages。
• 节目资源不包含计数 — 从经过筛选的列表的 meta.totalCount 推导单集数和订阅者数。
• 分析数据是按日数组，而非总计 — 累加 attributes.downloads （CLI 提供 downloads_total）；日期范围使用 dd-mm-yyyy，且必须成对提供；不要 解析行日期格式（文档各章节的示例不一致）。
• 只能通过控制面板创建节目 — 没有 POST /v1/shows； show-update 是唯一的节目写入操作。
• 速率限制为 10 req / 10 s — 触发 429 后，访问会被阻止 10 秒。没有 重试标头；请退避、批量导入订阅者、缓存响应，并使用 Webhook 保持数据最新。 Transistor 明确禁止将 API 用作网站后端（应改为解析 RSS 源）。
• episode[published_at] 使用节目所在时区（节目属性）， 而非 UTC；定时发布和回填日期都通过发布端点处理。
• 音频处理是异步的 — 附加音频后，请监控 audio_processing / processing_failure；发布尚未处理或处理失败的文件会向订阅者推送静音内容。
• 签名上传 URL 会过期（文档示例中约 600 s）：授权后，使用返回的 content_type 执行 PUT，并及时附加文件。
• 错误正文没有正式规范 — CLI 会处理 JSON:API errors[] 数组和简单的 {"message": ...} 对象，并将两者都展平为一行 stderr 输出；401（密钥无效）、403（角色权限）、404（ID 或路由无效）、429 （速率限制）各有不同提示。

适用场景

当需要通过 API 读取或操作 Transistor.fm 账户时，请使用此技能：验证 API 访问权限、浏览节目/单集（包括草稿和复合文档）、运行单集生命周期 （创建 → 附加音频 → 发布/定时发布/取消发布）、获取下载量分析时间范围、导入或撤销私密播客订阅者，以及注册 Webhook。

不适用场景

请勿将此技能用于其他播客托管平台（Buzzsprout、Libsyn、 Megaphone、Spotify for Creators——请使用它们各自的 API/工具）；音频 制作或编辑（这属于 ffmpeg 和 DAW 的范畴）；通用 RSS 源解析或网站渲染（直接解析源 XML——Transistor 表示 API 不应用作后端数据源）；创建新节目（API 无法实现，应通过控制面板创建）；或平台级分发问题 （提交至 Apple/Spotify 属于控制面板和 RSS 的范畴）。

参考文件

文件	用途
references/auth-and-basics.md	x-api-key 身份验证、密钥位置和角色范围、JSON:API 信封（data/attributes/relationships/included[]）及 jq 模式、分页参数、错误表现
references/endpoint-catalog.md	每条路由的方法、路径和参数（节目、剧集、发布、上传、分析、订阅者、webhook），以及不存在的路由
references/episode-publish-lifecycle.md	草稿/已排期/已发布状态机、准确的发布请求/响应结构、CLI 和 curl 中的创建→音频→发布方案、授权上传的绕行流程
references/gotchas-and-recipes.md	症状 → 原因 → 修复指南（404 用户路由、分页静默生效、429 风暴等）和多步骤工作流（批量排期、分析报告、订阅者导入、webhook）

可用脚本和先决条件

• scripts/transistor — 随附的 Python CLI（--json、--dry-run、 --force、--quiet、--verbose、--help 可用于所有命令）。仅导入标准库 和 requests；按文档所述的原样发送写入请求体 （方括号键形式字段）。
• scripts/test_transistor.py — 离线测试套件（兼容 pytest 和 unittest）；所有 HTTP 均使用预设的 JSON:API 文档进行模拟，完全不访问网络，没有实时调用用例（Transistor 是需要密钥的 API）。
• 实时命令需要 Python 3.8+、requests 和 TRANSISTOR_API_KEY（Account 页面 → API Access）。此技能不会启动任何服务。