hyperframes media-use 媒体供给链路搭建指南HeyGen 免费通道、本地模型与 Provider 选择【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本篇指南聚焦 HyperFrames 项目中的media-use技能Agent 媒体操作系统——一个将 BGM、音效、图片、图标、Logo、配音、调色、LUT 与头像视频统一收编为「一条 resolve 命令 一个冻结的本地文件」的媒体供给层。你将掌握如何安装并认证 HeyGen CLI 以解锁免费使用通道、各媒体类型对应的 Provider 级联顺序、本地模型mflux / Kokoro / Parakeet / LTX的 RAM 分级安装与调用、如何用--provider强制指定生成器以及--local-only离线模式的边界。一、核心设计原则media-use 不持有任何密钥在动手安装前先理解这套供给链路的底层哲学。media-use本身不保存任何 API 密钥所有外部工具的认证都由各自工具自己负责。这一点在 registry.mjs 的注释中写得很明确media-use holds no keys; each external tool owns its own auth。Provider 的注册表REGISTRY为每种媒体类型维护一个有序的 Provider 列表解析时按顺序尝试第一个返回非空结果者胜出。这样设计是为了让解析保持确定性——相同请求 → 相同 Provider → 相同文件 → 可复现的渲染结果。每种 Provider 被标注为三种成本档位之一见 registry.mjs构造器档位含义A(...)local本地、免费如 mflux、Kokoro、LTX、bundled.sfxN(...)network_free远程、免费如 HeyGen 目录搜索、svgl 等P(...)network_paid远程、可能产生计费如heygen.tts、heygen.video这套档位索引buildProviderTierIndex还带有约束校验同一个 Provider 名若被多个媒体类型引用其成本档位必须一致否则会在导入时报错——避免这次解析花不花钱取决于恰好命中的类型这种不确定性registry.mjs。二、安装与认证先装 HeyGen CLI免费使用路径生成能力整体围绕HeyGen CLI 的免费使用路径展开。bgm/sfx/image/icon 目录搜索、TTS语音和头像视频都依赖它因此这些能力要求heygen已安装并完成认证。# 1. 按官方 verified release 说明安装 HeyGen CLIhttps://developers.heygen.com/cli # 2. 升级到支持 OAuth 的版本 heygen update # 免费使用需要支持 OAuth 的 CLIv0.3.0 # 3. 登录——两种方式对应两种计费路径 heygen auth login --oauth # OAuth 免费订阅额度--api-key 则会走 API 信用计费这里有一个必须理解的关键区别免费配额挂在 OAuth 会话上。用--oauth登录可以走免费路径bgm/sfx/image/icon 目录搜索、TTS、头像视频而--api-key登录则直接消费 API 信用点数。因此 onboarding 一律引导到--oauth。版本门槛是硬性的media-use 统一要求heygen v0.3.0。在 heygen-cli.mjs 中可以找到该约束的源码依据v0.1.x/0.2.x 会直接拒绝 OAuth 会话heygen-cli cant use OAuth yet而 OAuth 恰恰是免费使用路径的必需品——低于该版本就完全无法走免费认证。即使你只用 API Key--doctor也会敦促旧版 CLI 升级。安装并认证后在解析任何资源之前先用--doctor校验环境node SKILL_DIR/scripts/resolve.mjs --doctor--doctor会检查哪些内容从 resolve.mjs 的实现可以看到bundled SFX 资源完整性、heygen是否在 PATH、版本号是否低于0.3.0含有新稳定版可用的提示、认证状态通过heygen auth status解析邮箱超时不武断判为未登录。任何检查项失败都会附带可执行的修复命令例如HEYGEN_NOT_FOUND_MESSAGE会提示你安装 CLIHEYGEN_NOT_AUTHENTICATED_MESSAGE会提示heygen auth login --oauth。三、Provider 总览每种媒体类型走哪条路media-use的能力覆盖表如下继承自 setup-providers.md 并补充源码细节类型Provider / 路径bgm/sfxheygen 目录免费使用路径imageheygen 搜索免费使用路径可选本地 mfluxcodeximage_gen升级通道voiceheygen tts 免费使用路径可选本地 Kokoro免费、设备端iconheygen asset search 免费使用路径logosvgl → simple-icons → GitHub org 头像 → 域名 favicon全部免费grade/lut本地 core-preset 映射、params/CDN look 索引、确定性buildCube兜底videoheygen 头像视频免费使用路径认证失败时提示登录可选本地 LTXvideogen阶梯。Image-to-video / photo-avatar / dub 保持手动heygenrecipes对照 registry.mjs 中的REGISTRY定义可以看到每类媒体实际的级联顺序bgmheygen.audio.soundsHeyGen 音频目录10k 曲目sfxheygen.audio.sounds→bundled.sfx内嵌 19 文件音效库imageheygen.asset.search75k 矢量素材→ 目录未命中则本地生成优先mflux.local按本机 RAM 规格自动选择最佳 FLUX 级模型→codex.image_genChatGPT 订阅的图片生成升级通道也是无本地模型可跑时的自动兜底iconheygen.asset.searchtypeiconlogosvgl→simple-icons→github.avatar→favicon.ddg。注意官方品牌标识绝不手工重绘且刻意不接入 HeyGen 素材搜索——因为它对品牌查询返回的是长得像的通用图标而非官方标识voiceheygen.tts标记为 paid见下文成本规则→kokoro.local免费、私有、离线兜底videoheygen.video→ltx.local本地生成式视频兜底成本规则X4与 paid 标记heygen.tts和heygen.video被标记为paid即使首月/每月有一定免费额度。原因见 registry.mjs 的注释客户端无法预知剩余免费额度所以凡是 Agent 主动发起的付费调用必须先与用户确认规则 X4用户主动要求的则直接执行。这也解释了为什么resolve --type video这种 Agent 发起的调用会先确认——heygen.video是 flagged paid 的有计量免费额度。# 免费使用路径的判定 # heygen.tts → 已登录 OAuth 时优先消费免费 web-plan 额度每月 10 分钟之后进入计费路径 # heygen.video → 新 API 用户可免费生成头像视频OAuth 会话在符合条件时挂接 web-plan 免费头像视频配额四、强制指定 Provider--provider当用户明确指定生成器时例如这张图用 codex 做传入--provider即可node SKILL_DIR/scripts/resolve.mjs --type image --intent gradient tech background --provider codex--provider会把解析钉死在该 Provider 上跳过默认的免费优先级联。其匹配规则支持全名如codex.image_gen或点分前缀如codex由 registry.mjs 的providerMatches统一实现保证校验与分派永不分歧。有两个重要的行为细节源码可验证强制 Provider 会绕过全部复用层。在 resolve.mjs 中forced !!args.provider使项目 manifest、实体、assets/扫描和全局缓存全部跳过——因为用 codex 重新生成不该静默返回一个来自其他 Provider 的缓存资产。--local-only是硬性安全开关优先级高于--provider。在 registry.mjs 的runProviders中p.network ctx?.localOnly会无条件跳过网络 Provider——即使你同时传了--provider heygen离线模式下也绝不发起网络请求宁可干净地 miss 并提示冲突也不静默联网。五、离线模式--local-onlynode SKILL_DIR/scripts/resolve.mjs --type image --intent gradient tech background --local-only--local-only跳过所有网络 Provider包括免费的 HeyGen 系列只保留项目.media/ 全局缓存~/.media/ 已安装的本地 Provider。对纯 HeyGen 类型的媒体如 bgm、icon这意味着不会有任何新的解析结果——只能命中缓存。一个常见误区需要澄清--local-only下image类型仍可走mflux 本地生成一旦模型缓存只是跳过 codex 云端升级而voice类型则退化为 Kokoro 本地 TTS。六、CLI 工具清单装什么、装在哪、服务谁resolve自动级联每个 Provider 实际 shell 一个 CLI。只有ffmpeg/ffprobe是工具运行的硬性前置引擎本身也依赖它其余均为按需安装工具服务对象安装方式ffmpeg/ffprobeadopt 探测、smart-grade signalstats、剪切、duck bake、loudnorm系统包macOSbrew install ffmpegheygen目录bgm/sfx/image/icon TTSvoice 头像视频——免费使用路径按官方 verified release 说明安装然后heygen auth login --oauth需 v0.3.0mflux-generate本地图片生成FLUX最适配 RAMuv venv ~/.venvs/mflux VIRTUAL_ENV~/.venvs/mflux uv pip install mflux0.9.6codex图片生成升级通道ChatGPT 订阅Codex CLI通过 ChatGPT 登录认证归它自己管parakeet-mlx本地转写默认 ASR效果最佳uv venv ~/.venvs/parakeet VIRTUAL_ENV~/.venvs/parakeet uv pip install parakeet-mlxltx-2-mlx本地视频生成git clone https://github.com/dgrauet/ltx-2-mlx cd ltx-2-mlx uv sync --all-extrasnpx hyperframesKokoro TTSvoice、whisper.cpp转写兜底、remove-background经 hyperframes CLIwhisper.cpp 首次使用时构建macOS 走 Homebrew否则 gitcmake模型从 HuggingFace 下载关键设计本地工具是可选opt-in替代方案——装一个就为对应类型解锁一条免费、私有、设备端缓存后离线可用的路径优先级可高于或先于 HeyGen。某个工具不在 PATH 上时其 Provider 会向 stderr 打印一行诊断信息然后 resolve 在有其他 Provider 的情况下自动向下级联例如无mflux→ codex 图片升级无parakeet-mlx→ whisper.cpp。只有 ffmpeg/ffprobe 是唯一硬性要求。七、RAM 分级模型阶梯机器能跑什么resolve 说了算本地模型的选型不靠猜而是由scripts/lib/local-models.mjs基于可用 RAM做规格校验spec-check。该模块定义了五大能力阶梯tts、asr、upscale、videogen、imagegenlocal-models.mjs。Agent 可以通过describeModelLadder(cap, specs)查看本机每个阶梯的全部候选——哪些能跑、为什么能跑、哪些太大跑不了。图片生成imagegen阶梯档位模型可用 RAM 需求备注mediumFLUX.1 schnell int4~8GB--low-ram24GB 机器上 ~20s/512px已验证快速largeFLUX.2 Klein 4B int4~32GB更高质量全驻留xlargeQwen-Image~64GB顶级质量仅限 64GB Mac这个表里藏着两个用真金白银换来的坑源码注释完整记录官方 FLUX 仓库被 HuggingFace 门禁license wall因此指向的是非门禁的社区 4-bit 重新上传版本如dhairyashil/FLUX.1-schnell-mflux-4bit自带 VAE、自包含。medium 档--low-ram是强制项。没有它FLUX 的 T5-XXL 文本编码器 transformer 会击穿 24GB 进入 swap——一次 768x512 生成耗时90 分钟加上--low-ram组件流式从磁盘加载后同一台机器 512x512 只需约 20 秒、7.6GB 空闲即可。所以该档位needs.ramMB是流式下限而非常驻占用。选型逻辑selectModel是能跑的最大模型带显式rank的按 rank质量优先如 ASR 场景否则按 RAM 占用降序生成质量代理指标。selectModelLadder则返回全部可跑模型的有序列表调用方可以逐级降级——某个条目不可用权重被门禁、二进制缺失、OOM就降级到下一档而不是让整条本地路径失败。视频生成videogen阶梯档位模型需求备注mediumLTX 2.3 MLX int4q4~16GB已在 24GB 统一内存验证512x320 x 33 帧冷启动约 19 分钟含文本编码器下载带音频的 t2v。尺寸必须是 64 的倍数largeLTX 2.3 MLX int8q8~32GB两阶段上游生产默认质量更高但需要 87.5GB 下载 vs q4 的 59.7GB是实打实的取舍LTX 阶梯的sizeMB是整个仓库的体积因为运行时会无过滤地snapshot_download整个 repo两阶段还需要 transformer-dev transformer-distilled x2 空间放大器的组合。此外 bf16 版本已被门禁HTTP 401无法下载因此用 q8 替代。TTS 与 ASR 阶梯ttsKokoromedium330MBCPU、快于实时、原生逐词时间戳默认底线→ fish-speechlarge1.1GB需 16GB RAM GPU 12GB VRAM零样本音色克隆会议场景首选逐词时间戳需 WhisperX 强制对齐。asrParakeet-TDT 0.6Bsmall 档但rank: 0钉在最前→ WhisperXmediumCPU-only 兜底。Parakeet 的选型逻辑是质量不是尺寸的典型案例0.6B 的 Parakeet 在 Open ASR Leaderboard 平均 WER ~6.05%优于 whisper-large-v3 的 7.44%嘈杂音频 4.73% vs 5.96%whisper-v3 在会议场景甚至幻觉到 308% WER且快 5-10 倍。这是 local-models.mjs 中明确记录、并在 24GB Mac 上实测的结论。Cohere Transcribe 2B 虽然纸面登顶但 mlx-audio 量化版产出 token 乱码且慢 40-70 倍因此未被接入。RAM 校验的机制meetsSpecslocal-models.mjs的判定优先使用可用 RAM探测到的真实预算扣除系统与已开应用占用无探测结果时才回退到总 RAM同时检查 GPU 存在性与显存。Apple Silicon 的统一内存会被计入 VRAM。八、--doctor与错误分类安装问题的自诊断当heygen调用失败时heygen-cli.mjs 的classifyHeygenErrorResult会把错误归类为not_found/not_authenticated/outdated/rate_limited/other并映射到可操作的提示。几个值得注意的实现细节not_found只认 ENOENT 或 command not found——避免把 CLI 自身的资源错误如过期的 voiceId 报 voice not found误判为需要重装 CLI。401 判定使用\b401\b词边界避免 request-idreq-401abc、URL 或重试头被误分类为认证失败。not_found与outdated会生成 remediation补救建议reportHeygenFailure会将其暂存resolve 主流程在落盘记录时可消费并附加为advisory。每次 provider 失败都会异步上报遥测事件media_use_provider_error且通过flushHeygenFailureTracking确保短生命周期进程退出前 flush 完毕。九、关于X-HeyGen-Client-Source头与隐藏命令heygen asset search是发布前的隐藏命令heygen --help看不到但它可以运行。所有 media-use 发起的 heygen 调用——TTS、头像视频、目录搜索——都会通过共享常量HEYGEN_CLIENT_SOURCE_ARGVheygen-cli.mjs附加白名单头X-HeyGen-Client-Source: media-use需要 v0.3.0这样用量会正确计入计费/资源元数据并出现在 API 仪表盘中。只读的发现类命令avatar list、voice list不需要此头。在 heygen-search.mjs 中可以看到搜索调用以argv 数组 execFileSync无 shell方式执行query 等参数作为字面量传入——没有引号注入面子命令是硬编码字符串超时 15 秒--min-score服务端分数下限仅音频 Provider 传递asset search后端不接受该参数。十、配套资源与下一步完整命令、flags、复用规则与 ingest--from、adopt--adopt说明见 resolve 参考文档——包括--candidates/--reuse的跨项目语义复用流程以及完全相同的请求自动复用、模糊匹配永不自动应用的确定性底线。装好 Provider 之后如何对媒体做剪切、重构图、拼接、转写、字幕剪切、duck、loudnorm 发布响度、错误扩散抖动Floyd-Steinberg / Atkinson 等 8 种算法、HEVC 源处理见 媒体操作参考。其中的 dither 与转写均提供了完整命令示例处理后用resolve --from out --type type把产物登记进账本与全局缓存。本地模型阶梯的权威定义与逐档 install/invoke 模板见 local-models.mjsAgent 可直接调用describeModelLadder(cap, specs)查看本机适配情况。技能的入口与全量能力地图见 SKILL.md。总结media-use的供给链路是一套免费优先、本地优先、RAM 分级、级联确定性的媒体解析体系。装好heygen v0.3.0并用--oauth登录即可解锁绝大多数免费能力需要离线/隐私/省钱场景时按 RAM 阶梯装一个 mflux、Kokoro、Parakeet 或 LTX 就能把对应类型切换为纯本地路径--provider负责显式钉选--local-only负责硬性离线而--doctor和错误分类体系负责让环境问题一眼可查、一键可修。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考