AI导哈

数字人视频生成服务

一款基于MCP协议的数字人/说话头像视频生成服务，支持通过文本或音频输入将肖像照片转换为说话视频，适用于内容创作、教育、娱乐等多种场景。

  • by kevinten-ai
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kevinten-ai/mcp-avatar

使用说明

mcp头像

AI digital human / talking head video generation MCP server.
Generate videos of portrait photos speaking from text or audio.
Providers: Hedra + D-ID. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

中文文档

特性

  • 说话的头一代 --将任何肖像照片转换为讲话视频
  • 文本或音频输入 --提供文本（自动TTS）或预先录制的音频
  • 2供应商 --Hedra（最佳品质）+D-ID（广泛使用）
  • 异步两步 --提交生成，轮询结果（与mcp视频生成模式相同）
  • 自动下载 --自动将生成的视频保存到本地磁盘
  • 提供商切换 --通过以下方式为每个请求选择最佳提供商 provider 参数

建筑学

运作原理

User Prompt -> AI Assistant (Claude / Cursor) -> MCP Server -> Provider API
                                                    |
                                        generate_talking_head() -> task_id
                                        query_avatar_status(task_id) -> download to disk

两个提供商都使用 异步模式：提交生成请求，获取任务ID，然后轮询直到完成。MCP服务器透明地处理这个问题——AI助手调用 generate_talking_head那么 query_avatar_status 循环播放，直到视频准备就绪。

支持的提供商

提供商 API 免费层 质量 最适合
多面体 角色API 注册时的试用学分 最佳质量的演讲头 生产质量
D-ID 对话API 5分钟免费视频 质量好，语言支持广泛 快速原型

供应商选择指南

Need a talking head video?
  |-- Best quality?
  |   |-- hedra (best lip sync and expression)
  |
  |-- Free trial?
  |   |-- did (5 min free)
  |   |-- hedra (trial credits)
  |
  |-- Have pre-recorded audio?
  |   |-- Both providers support audio input
  |
  |-- Text only (need TTS)?
      |-- Both providers have built-in TTS

快速开始

1.克隆并安装

git clone https://github.com/kevinten-ai/mcp-avatar.git
cd mcp-avatar
uv sync

2.配置MCP

仅配置要使用的提供程序。至少需要一个API密钥。

Claude Code (CLI) — recommended 
# Hedra only
claude mcp add -s user mcp-avatar \
  --env HEDRA_API_KEY=your_key \
  -- uv --directory /path/to/mcp-avatar run avatar-gen

# D-ID only
claude mcp add -s user mcp-avatar \
  --env DID_API_KEY=your_key \
  -- uv --directory /path/to/mcp-avatar run avatar-gen

# Both providers
claude mcp add -s user mcp-avatar \
  --env HEDRA_API_KEY=your_key \
  --env DID_API_KEY=your_key \
  -- uv --directory /path/to/mcp-avatar run avatar-gen
Claude Desktop / Cursor (JSON config) 
{
  "mcpServers": {
    "mcp-avatar": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-avatar", "run", "avatar-gen"],
      "env": {
        "HEDRA_API_KEY": "your_key",
        "DID_API_KEY": "your_key"
      }
    }
  }
}

3.使用它

让你的AI助手生成一个会说话的头部视频：

"Make the person in photo.jpg say 'Hello, welcome to my channel'"

助理会打电话来 generate_talking_head，等等，然后打电话 query_avatar_status 下载结果。

工具（共3个）

发电机_通话头

从肖像照片+音频或文本生成会说话的头部视频。

参数 类型 必填 说明
image_path string 是 肖像照片的路径（本地文件或URL）
text string 否* 要说话的文本（自动TTS）。 *需要文本或audio_path。
audio_path string 否* 预先录制的音频文件。*需要文本或音频路径。
provider string 否 提供者：hedra，确实如此。默认值：第一个可用。
output_directory string 否 保存视频的目录。默认值：。/输出

query_avatar_status

检查生成状态并下载结果视频。

参数 类型 必填 说明
task_id string 是 来自generate_talking_head的任务ID
provider string 是 使用的提供程序
output_directory string 否 保存视频的目录

list_提供者

列出所有可用的化身生成提供商，并附上描述和定价。

API密钥注册指南

1. Hedra — Best Quality Talking Heads
项目 详细信息
平台 Hedra
URL https://www.hedra.com
免费等级 注册时试用积分
Env Var HEDRA_API_KEY

步骤：

  1. 访问https://www.hedra.com->注册
  2. 转到API设置/开发人员面板
  3. 创建API密钥->副本

Hedra能够产生最优质的唇形同步和面部表情。

2. D-ID — Digital Human Platform
项目 详细信息
平台 D-ID
URL https://www.d-id.com
免费等级 5分钟免费视频
Env Var DID_API_KEY

步骤：

  1. 访问https://www.d-id.com->注册
  2. 首选https://studio.d-id.com/account-settings->API密钥
  3. 创建一个API密钥->副本（密钥已经是base64编码的）

D-ID通过内置TTS支持100多种语言，并具有广泛的生态系统支持。

环境变量

变量 提供者 必填
HEDRA_API_KEY Hedra 至少有一个提供商
DID_API_KEY 必须配置D-ID
AVATAR_OUTPUT_DIR 所有提供程序 可选，默认值： ./output

故障排除

常见错误

错误 根本原因 解决方案
No providers configured 未设置API密钥 在MCP环境配置中至少设置一个提供程序的API密钥
Unknown provider: xxx 拼写错误或提供程序未配置 检查 list_providers 有关可用选项
Either text or audio_path is required 未提供语音输入 也提供 text 或 audio_path 参数
Still processing 视频尚未准备好 正常--呼叫 query_avatar_status 30秒后再次

提供商特定错误

错误 提供程序 解决方案
Hedra upload init failed Hedra 检查API密钥是否有效，文件是否存在并且是支持的图像格式
D-ID API error: Unauthorized D-ID 检查 DID_API_KEY 正确（应采用base64编码）
Auto-download failed 两个 视频URL都可能已过期。请重试查询或重新生成。

提示

  • 图像质量很重要 --使用清晰的正面肖像照片以获得最佳效果
  • 音频格式 --MP3和WAV得到了广泛支持。将音频保持在60秒以下。
  • 轮询间隔 --两个提供者通常需要30-120秒。AI助手将自动进行投票。

项目结构

src/avatar_gen/
|-- __init__.py
|-- __main__.py
|-- server.py              # MCP server + tool handlers
|-- providers/
    |-- __init__.py        # BaseProvider abstract class + AvatarResult + registry
    |-- hedra.py           # Hedra Character API
    |-- did.py             # D-ID Talks API

添加新提供者

  1. 创建 src/avatar_gen/providers/your_provider.py
  2. 实施 BaseProvider （属性： name, description, pricing_info；方法： generate(), query())
  3. 注册于 server.py:_init_providers() 使用env-var检查
  4. 提供者自动出现在 list_providers 和 generate_talking_head 工具模式

本地开发

git clone https://github.com/kevinten-ai/mcp-avatar.git
cd mcp-avatar
uv sync

# Run directly
uv run avatar-gen

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run avatar-gen

相关项目

许可证

麻省理工学院——见 许可证 了解详情。

相关 MCP