TokenHub 媒体 API 是为企业打造的统一 AI 媒体网关能力：只需一次接入，就能在同一个网关上调用图像生成、语音合成、语音识别、视频生成和音乐创作等接口。所有请求共享同一套鉴权、模型白名单、配额、审计与用量归因体系，让每一次生成请求都可控、可追踪、可归因。

什么是 TokenHub 媒体 API

传统做法是每个供应商一套 SDK、一套密钥、一套计费逻辑，团队想同时用图像生成 API、语音合成接口和视频生成网关，维护成本会快速膨胀。TokenHub 媒体 API 的思路相反：把多家供应商的媒体模型收敛到 OpenAI 兼容和 Gemini 原生等标准协议之下，开发者面向 TokenHub 的 Base URL 发起请求即可。

下图展示了 TokenHub 企业 AI 网关的多实例部署架构：客户端统一进入网关，后端按需转发给各模型供应商（Model Providers），并依赖共享的 PostgreSQL 保存配额、会话与审计状态。

对新手而言，它带来三个直接好处：

• 一套 Key 走天下：用项目级 API Key 调用图像、音频、视频、音乐模型，不再为每个供应商单独开户管理
• 协议统一：图像走/v1/images/*，音频走/v1/audio/*，视频与音乐走/v1/responses，无需记忆各家私有协议
• 治理内建：鉴权、模型白名单、文本策略、请求/响应钩子、审计日志与 Token 用量归属自动生效

媒体 API 接口覆盖一览

TokenHub 支持 DMXAPI 生态常用的媒体协议族。不同创作场景对应的接口如下：

视频类模型通过/v1/responses提交并查询任务，无需引入新的/v1/videos端点——提交后保存返回的任务 ID，用辅助查询模型轮询直到上游完成即可。

💡 完整的接口参数与厂商差异说明见官方文档：docs/zh-CN/media-apis.md（英文版本：docs/media-apis.md）

四步快速接入：配置供应商与发布媒体模型

在控制台中完成配置是接入媒体 API 的第一步。登录后即可进入控制台进行供应商与模型管理。

第 1 步：添加上游供应商

添加一个 OpenAI-compatible 类型供应商，填入媒体供应商的 Base URL 与凭证；如需 Gemini 原生媒体能力，再添加一个 Gemini 类型供应商指向同一上游账户。供应商通道的管理入口见管理员指南：docs/zh-CN/administrator-guide.md。

第 2 步：发布公开模型并选择媒体模态

在模型目录中发布公开模型，将路由映射到准确的上游模型 ID，并把模态设置为image、video或audio（音乐同样使用audio）。这一步非常关键：媒体请求会自动跳过响应缓存，避免复用历史生成结果或读到过期的任务状态。

第 3 步：同时发布辅助模型

视频和声音克隆类模型通常还有"查询/上传"配套接口，例如seedance-2-0-get、MiniMax-Hailuo-query等。务必把它们一并发布，并确保项目密钥获准访问整个流程所需的全部模型。

第 4 步：固定路由到同一供应商账户

将生成模型与辅助模型的路由固定到同一供应商账户/资源下，任务 ID、文件 ID（包括大整数）会原样透传。需要任务命名空间隔离的租户，应使用独立的上游账户。

调用示例：语音合成、识别与视频生成

配置完成后，使用项目 Key 即可发起请求。以下示例来自官方文档，替换为你的 TokenHub 地址与 Key 就能运行。

语音合成——直接把生成的 MP3 保存到本地：

curl https://tokenhub.example/v1/audio/speech \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"speech-2.6-hd","input":"Hello from TokenHub","voice":"male-qn-qingse","response_format":"mp3"}' \ --output speech.mp3

视频生成——先提交任务，再用辅助模型轮询直到完成：

# 提交视频生成任务 curl https://tokenhub.example/v1/responses \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"doubao-seedance-2-0-260128","input":[{"type":"text","text":"A calm ocean at sunrise"}],"duration":4,"resolution":"720p"}' # 保存返回的 id，查询直到上游报告完成 curl https://tokenhub.example/v1/responses \ -H "Authorization: Bearer $TOKENHUB_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"seedance-2-0-get","input":"TASK_ID_FROM_SUBMISSION"}'

更多端点示例与参数说明，可以在内置的 API 文档页面中查看，它会自动列出当前 Base URL、鉴权方式与可用端点：

用量计量与治理：媒体创作如何计费与留痕

企业关心的另一个核心问题是"这笔生成费用算在谁头上"。TokenHub 媒体 API 的计量与治理机制如下：

• 按上游真实用量计费：Token 计费直接采用上游返回的用量；语音转录会保留audio_tokens明细，而二进制音频、字幕文本或未上报 Token 的供应商不会被"虚构"出 Token 成本
• 失败不重复扣费、不重复生成：结果不确定的提交失败不会自动换路由再次生成，明确的鉴权/限流拒绝仍可触发故障切换
• 审计不留存媒体本体：审计记录只保存模型、脱敏后的策略决定、内容类型和字节数，不保存上传或生成的媒体内容，兼顾合规与安全
• 文本策略全覆盖：input、prompt、negative_prompt等字段（包括重复的 multipart 字段）都会经过文本前置策略检查

用量与成本在控制台的 Usage Analytics 页面按部门和个人排名展示，方便团队核对媒体创作开销：

此外，媒体接口有明确的大小保护：请求默认上限 32 MiB（由TOKENHUB_MAX_MULTIMODAL_REQUEST_BYTES控制），multipart 最多 128 个部分，响应最多缓冲 128 MiB 后交付，且保留供应商原始内容类型。

总结与延伸阅读

TokenHub 媒体 API 把图像生成、语音合成、视频与音乐创作收敛到同一个企业级 AI 网关之下：标准协议、统一鉴权、真实用量计费、完整审计留痕。如果你正在为团队搭建多模态创作平台，只需四步配置即可把现有 OpenAI 风格客户端无缝切换过来。

想深入了解，可以继续阅读这些资料：

• 媒体 API 完整参考：docs/zh-CN/media-apis.md
• Codex 生图 API 调用与测试：docs/zh-CN/codex-image-generation-api.md
• 管理员指南（供应商、模型目录与路由）：docs/zh-CN/administrator-guide.md
• 团队负责人指南（项目 Key 与成本归因）：docs/zh-CN/team-leader-guide.md
• 媒体 HTTP 处理相关源码入口：backend/internal/server/gateway_media_http.go、backend/internal/server/media_responses.go