human-avatar

# Human Avatar — 阿里云口播视频生成

## 三种模式

| 模式 | 接口 | 认证 | Region | 说明 |
|------|------|------|--------|------|
| **EMO** | DashScope | `DASHSCOPE_API_KEY` | **cn-beijing** | 人像+音频→口播，需先 detect |
| **AA** (Animate Anyone) | DashScope | `DASHSCOPE_API_KEY` | **cn-beijing** | 人像+动作视频→全身动画 |
| **灵眸** (LingMou) | 独立产品 SDK | AK/SK | **cn-beijing** | 基于模板的数字人口播 |
| **VideoRetalk** (视频换人) | DashScope | `DASHSCOPE_API_KEY` | **cn-beijing** | 视频角色替换 |

> ⚠️ **Region 固定为 cn-beijing**，API Key 需在北京地域开通，不可与新加坡 Key 混用。

## 前置条件

```bash
pip install requests dashscope oss2
# 灵眸额外需要:
pip install alibabacloud-lingmou20250527 alibabacloud-tea-openapi
```

环境变量：
```bash
export DASHSCOPE_API_KEY=sk-xxxx          # DashScope API Key（百炼控制台获取）
export ALIBABA_CLOUD_ACCESS_KEY_ID=xxx    # 灵眸用
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxx
export OSS_BUCKET=xxx                     # 本地文件上传用
export OSS_ENDPOINT=oss-cn-beijing.aliyuncs.com
```

## EMO 工作流（两步）

```
Step 1: emo-detect-v1 检测人脸 → 获取 face_bbox, ext_bbox
  ↓
Step 2: emo-v1 提交生成 → task_id
  ↓
轮询 GET /api/v1/tasks/{task_id} → SUCCEEDED → video_url
```

```bash
python scripts/portrait_animate.py \
  --image-url "https://example.com/portrait.jpg" \
  --audio-url "https://example.com/speech.mp3" \
  --download
```

## 灵眸工作流（基于模板）

```
1. 查询模板列表 → templateId（已存 digital_human_template.json）
2. CreateBroadcastVideoFromTemplate (variables 替换 text_content)
3. 轮询 ListBroadcastVideosById → SUCCESS → videoURL
```

```bash
python scripts/avatar_video.py \
  --template-id "BS1b2WNnRMu4ouRzT4clY9Jhg" \
  --text "大家好，欢迎收看今天的科技新闻。" \
  --download
```

## 一键 Demo Pipeline

```bash
# EMO
python scripts/demo_pipeline.py --mode emo --image ./face.jpg --audio ./speech.mp3 --download

# AA
python scripts/demo_pipeline.py --mode aa --model <AA_MODEL_NAME> --image-url https://... --vide...