飞影数字人

2026年9月3日修改

在 Codex 中通过 MCP 使用飞影

通过 MCP（Model Context Protocol），可以把飞影的数字人、声音和视频能力接入 Codex。配置完成后，你可以直接在 Codex 的对话中查询账户能力、创建任务并查询任务状态。

本文使用远程 Streamable HTTP MCP 服务和 Bearer Token。飞影 MCP 正式环境地址已写入下方命令；文章不会提供或保存任何个人 Token。

选择接入方式

两种方式的结果相同。快速接入不是 OAuth 授权：为了保护你的 Token，Codex 不会要求你把 Token 发到对话中。

开始前：准备 Token

当前飞影 MCP 接入地址为 https://hifly.cc/mcp，无需手动修改。登录飞影后，进入智能体 → API 明细，复制你的飞影 API Token。

安全提醒：Token 等同于访问凭证。不要把它粘贴到聊天记录、截图、Git 仓库或 config.toml 中；建议只放在本机环境变量里。

以下示例中只有 Token 需要替换为你自己的值：

MCP Server URL: https://hifly.cc/mcp
飞影 API Token: <你的飞影 API Token>

在 Codex 中连接飞影 MCP

Codex 支持远程 Streamable HTTP MCP 服务。你可以使用命令行添加，也可以手动维护配置文件；二选一即可。

1. 设置 Token 环境变量

请按所使用的 Codex 方式设置环境变量。Token 不要写入代码仓库、config.toml 或聊天记录。

macOS Codex 桌面应用 / IDE

在“终端”中运行以下命令，输入时 Token 不会显示。完成后完全退出并重新打开 Codex 或 IDE。

read -rs "HIFLY_API_TOKEN?粘贴飞影 API Token: "
echo
launchctl setenv HIFLY_API_TOKEN "$HIFLY_API_TOKEN"
unset HIFLY_API_TOKEN

Codex CLI

在准备启动 Codex 的同一个终端中运行：

export HIFLY_API_TOKEN="<你的飞影 API Token>"

Windows PowerShell：

$env:HIFLY_API_TOKEN = "<你的飞影 API Token>"

export 只对当前终端会话生效；桌面应用不会自动继承已打开终端里的变量。Token 刷新或替换后，重新设置变量并重启客户端。

2. 用命令添加服务

先检查是否已经配置过 hifly。如果存在且地址正确，无需重复添加；如果地址不同，先确认后再更新。不要为排错自动删除其他 MCP 服务。

codex mcp get hifly

仅在没有 hifly 配置时，在已经设置上述环境变量的终端中运行：

codex mcp add hifly \
  --url "https://hifly.cc/mcp" \
  --bearer-token-env-var HIFLY_API_TOKEN

hifly 是这台电脑上显示的服务名称，可以保留不变。

或写入 config.toml

也可以编辑 Codex 配置文件：默认位置是 ~/.codex/config.toml；受信任项目可使用项目内的 .codex/config.toml。加入以下内容：

[mcp_servers.hifly]
url = "https://hifly.cc/mcp"
bearer_token_env_var = "HIFLY_API_TOKEN"

这里保存的是环境变量名称，而不是 Token 的明文。保存后需要重启 Codex 桌面应用、IDE 扩展或重新打开 Codex CLI。

验证连接

配置后依次检查：

codex mcp list
codex mcp get hifly

前两条命令只说明配置已写入。进入 Codex 后输入 /mcp，确认列表中出现 hifly；再执行下方账户查询，能够返回结果才表示 URL、Token 与服务连接都正常。如果你是在桌面应用或 IDE 中配置，保存后请完全退出并重新打开相应客户端。

官方 Codex 文档说明，Codex CLI、桌面应用和 IDE 扩展共享 MCP 配置；远程 HTTP 服务可通过 bearer_token_env_var 从环境变量读取 Bearer Token。

最小可运行示例

连接成功后，先执行一个只查询、不创建任务的请求，验证 Token、网络和工具加载是否正常：

帮我确认飞影账户是否已经接通，并告诉我当前套餐和可用积分；不要创建任何作品。

如果 Codex 能返回账户能力信息，说明飞影 MCP 已可使用。接下来可以先查询可用模板或账户能力，再决定是否创建数字人、声音或视频。

用模板批量生成视频

模板批量制作不是一个数组接口：智能体会对每条文案分别调用一次 create_video_by_template，并为每条视频返回独立的任务 ID。第一次建议先制作 3 条，避免同时处理人物、声音和本地素材。先让 Codex 帮你挑模板：

帮我看看飞影里有哪些视频模板，推荐一个最适合新手做第一支作品的，并说明我需要补充什么内容。先不要生成视频。

确认模板后，粘贴文案列表，让 Codex 先说明计划、等待明确确认，再逐条制作：

请使用刚才推荐的飞影模板，把下面每条文案分别制作成一支视频：
1. <第 1 条文案>
2. <第 2 条文案>
3. <第 3 条文案>

先告诉我将制作几支视频、每支使用的文案、比例和可能的消耗信息（如有；不要猜测）。等我回复“确认创建”后再开始；请逐支制作，不要重复提交。完成后按文案逐条告诉我任务结果，不要自动反复查询。

需要查看结果时，使用 get_task_status 逐条查询相同的 task_type 与 task_id。PENDING 或 RUNNING 表示仍在处理；COMPLETED 后获取对应输出链接；ERROR 时记录任务 ID、请求 ID 和服务端错误信息，不要自动重试。

创建任务时的安全工作流

创建数字人、声音和视频会消耗资源，也可能产生不可逆的任务。建议按以下顺序操作：

先查询：使用 get_account_capabilities 或 list_templates 了解可用能力和模板。
再列清单：批量制作前，让 Codex 列出每条文案和本次总数量；每条视频都是独立任务。
描述清楚：说明素材来源、数字人、声音、文案、比例和预期成片。
先确认：让 Codex 在创建前复述将要提交的参数，以及服务返回的消耗信息（如有）；确认无误后再执行。
记录任务：创建后保存返回的 task_type 与 task_id。
查询状态：使用 get_task_status 查询，不要因为等待而重复创建同一任务。

需要使用本地素材时，先让 Codex 调用 upload_material，只传文件扩展名（例如 mp4 或 png）。它会返回 upload_url、content_type 和 file_id；随后由 Codex 通过 HTTP PUT 把本地文件的原始字节上传到 upload_url。PUT 成功后，才能把 file_id 传给创建数字人、声音或视频的工具。上传请求不需要、也不能携带飞影 Token。

常见问题与排错

提示 401 或 INVALID_TOKEN

重新复制 Token，检查前后是否带有空格、换行或错误的 Bearer 前缀。
确认环境变量名称是 HIFLY_API_TOKEN，并且启动 Codex 的终端确实拥有该变量。
如果 Token 已刷新或替换，旧 Token 会失效；更新环境变量后重启 Codex。

Codex 中看不到飞影工具

检查 MCP Server URL 是否完整，尤其是末尾的 /mcp。
运行 codex mcp list，确认服务已添加。
在 Codex 中输入 /mcp 查看连接状态；桌面应用和 IDE 扩展需完全重启。

提示 429 或 RATE_LIMITED

请读取服务返回的 retry_after_seconds，等待后再试。不要无限重试或并发重复提交创建请求。

上传素材失败

upload_material 只申请上传地址，不会自动读取或上传文件。确认先用 file_extension 取得上传信息，再用 HTTP PUT 上传文件原始字节；Content-Type 必须使用工具返回的值，且 PUT 成功前不能使用 file_id。如果 upload_url 已过期，请重新申请，不要把飞影 Token 发给 OSS。

视频、声音或数字人一直未完成

使用创建任务时返回的 task_type 和 task_id 调用 get_task_status 查询。PENDING / RUNNING 时继续等待；若为 ERROR，记录任务 ID、请求 ID 与服务端错误信息后再排查。不要自动重新创建，以免产生重复任务和额外消耗。

更新或移除配置

要更换 MCP 地址或 Token，更新环境变量和配置后重启 Codex。若不再使用，可运行：

codex mcp remove hifly

更多接口、参数和能力变更以飞影 API V2 文档为准。Codex MCP 配置规则可参考 OpenAI 官方 Codex MCP 文档。