# AIOM 智能创作平台 - 完整功能指南

> **SKILL名称**: aiom-agent-workflow  
> **描述**: AIOM智能体工作流API - 供Coze/Dify等AI智能体调用。AIOM负责：素材管理+对口型视频生成；智能体自行处理：字幕+BGM+画中画。当需要自动化生成带货/讲解短视频时调用此技能。  
> **版本**: 2.0  
> **API基础URL**: `https://www.aiom.com.cn`  
> **MCP端点**: `https://www.aiom.com.cn/mcp/sse`  
> **最后更新**: 2026-05-10

---

## 🎯 快速开始（智能体必读）

### 1. 获取认证凭证

**方式A：注册+登录（推荐）**
```http
# 注册账号（手机号或邮箱）
POST https://www.aiom.com.cn/php/register.php
Content-Type: application/json

{
  "phone": "13800138000",     // 或 "email": "user@example.com"
  "password": "123456",
  "shopName": "测试店铺"      // 可选
}

# 登录获取Token
POST https://www.aiom.com.cn/php/login.php
Content-Type: application/json

{
  "identifier": "13800138000",  // 手机号或邮箱
  "password": "123456"
}

# 响应:
{
  "code": 200,
  "data": {
    "token": "abc123...",      // ← 保存这个Token，后续所有API都要用
    "userId": 123,
    "balance": 10.00
  }
}
```

**方式B：API Key（适合智能体自动化）**
- 在AIOM平台申请API Key
- 认证头: `X-API-Key: YOUR_API_KEY`

### 2. 认证方式

所有API调用需要在请求头中添加认证：

```http
# Bearer Token方式
Authorization: Bearer YOUR_TOKEN

# 或 API Key方式
X-API-Key: YOUR_API_KEY
```

---

## 📦 核心功能模块

---

## 模块一：素材管理

### 1.1 获取录音列表（音色素材）

**功能**: 获取用户上传的所有录音文件，用于提取音色。

**API**: `GET /php/get_recordings.php`

**认证**: Bearer Token 或 API Key

**示例请求**:
```http
GET /php/get_recordings.php HTTP/1.1
Host: www.aiom.com.cn
Authorization: Bearer YOUR_TOKEN
```

**示例响应**:
```json
{
  "recordings": [
    {
      "id": 1,
      "title": "男声-客服",
      "tags": "男声,客服,正式",
      "audio_url": "https://www.aiom.com.cn/uploads/audio/xxx.mp3"
    },
    {
      "id": 2,
      "title": "女声-带货",
      "tags": "女声,活泼,带货",
      "audio_url": "https://www.aiom.com.cn/uploads/audio/yyy.mp3"
    }
  ],
  "count": 2
}
```

**使用建议**:
- 智能体根据 `tags` 字段匹配用户需要的音色
- 如用户需要"男声客服"风格，查找 `tags` 包含"男声,客服"的录音

---

### 1.2 获取视频列表（人物素材）

**功能**: 获取用户上传的所有视频素材，用于对口型合成。

**API**: `GET /php/get_videos.php`

**认证**: Bearer Token 或 API Key

**示例请求**:
```http
GET /php/get_videos.php HTTP/1.1
Host: www.aiom.com.cn
Authorization: Bearer YOUR_TOKEN
```

**示例响应**:
```json
{
  "videos": [
    {
      "id": 1,
      "title": "正面半身-西装",
      "tags": "正面,半身,西装,正式",
      "video_url": "https://www.aiom.com.cn/uploads/video/xxx.mp4"
    },
    {
      "id": 2,
      "title": "侧面全身-休闲",
      "tags": "侧面,全身,休闲,户外",
      "video_url": "https://www.aiom.com.cn/uploads/video/yyy.mp4"
    }
  ],
  "count": 2
}
```

**使用建议**:
- 根据 `tags` 匹配用户需要的视频风格
- 如用户需要"正面正式"风格，选择 `tags` 包含"正面"的视频

---

### 1.3 获取BGM列表

**功能**: 获取背景音乐素材库。

**API**: `GET /php/get_bgm_list.php`

**认证**: Bearer Token 或 API Key

**示例响应**:
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "轻快音乐",
      "url": "https://www.aiom.com.cn/uploads/bgm/xxx.mp3"
    }
  ]
}
```

---

## 模块二：语音合成

### 2.1 语音合成（文字→语音）

**功能**: 输入文本和源音频，合成指定音色的语音。

**API**: `POST /plugin_api_simple/voice_synthesis.php`

**认证**: Bearer Token 或 API Key

**请求体**:
```json
{
  "text": "大家好，欢迎来到我们的店铺，今天推荐一款超级好用的产品！",
  "audio_url": "https://www.aiom.com.cn/uploads/audio/source.mp3",
  "speed": 1.0,
  "pitch": 1.0
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` | string | ✅ | 要合成的文本内容 |
| `audio_url` | string | ✅ | 源音频URL（用于提取音色） |
| `speed` | number | ❌ | 语速 0.5-2.0，**默认 1.2**（推荐） |
| `pitch` | number | ❌ | 音调 0.5-2.0，默认 1.0 |

**响应**:
```json
{
  "success": true,
  "data": {
    "task_id": "VT_12345",
    "status": "processing",
    "message": "语音合成任务已创建"
  }
}
```

---

### 2.2 查询语音合成状态

**功能**: 查询语音合成任务进度。

**API**: `GET /plugin_api_simple/query_status.php?task_id=VT_12345`

**认证**: Bearer Token 或 API Key

**响应（处理中）**:
```json
{
  "success": true,
  "data": {
    "task_id": "VT_12345",
    "status": "processing",
    "message": "正在合成中..."
  }
}
```

**响应（成功）**:
```json
{
  "success": true,
  "data": {
    "task_id": "VT_12345",
    "status": "success",
    "audio_url": "https://www.aiom.com.cn/uploads/audio/result.mp3",
    "created_at": "2026-05-10 10:00:00",
    "updated_at": "2026-05-10 10:00:30"
  }
}
```

**智能体轮询逻辑**:
```javascript
async function waitForAudio(taskId, token, maxWait = 120) {
  for (let i = 0; i < maxWait / 5; i++) {
    await sleep(5000);
    const resp = await fetch(
      `https://www.aiom.com.cn/plugin_api_simple/query_status.php?task_id=${taskId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await resp.json();
    if (data.data.status === 'success') {
      return data.data.audio_url;
    }
    if (data.data.status === 'failed') {
      throw new Error('合成失败: ' + data.data.message);
    }
  }
  throw new Error('超时');
}
```

---

## 模块三：对口型视频合成

### 3.1 创建对口型任务

**功能**: 输入音频和视频，生成对口型视频（人物按音频说话）。

**API**: `POST /plugin_api_simple/lip_sync.php`

**认证**: Bearer Token 或 API Key

**请求体**:
```json
{
  "audio_url": "https://www.aiom.com.cn/uploads/audio/result.mp3",
  "video_url": "https://www.aiom.com.cn/uploads/video/source.mp4",
  "high_quality": true,
  "keep_audio": false
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `audio_url` | string | ✅ | 音频文件URL（要让人物说的话） |
| `video_url` | string | ✅ | 视频文件URL（人物素材） |
| `high_quality` | boolean | ❌ | 是否高清模式，默认 true |
| `keep_audio` | boolean | ❌ | 是否保留原视频背景音，默认 false |

**响应**:
```json
{
  "success": true,
  "data": {
    "task_id": "LS_67890",
    "type": "lip_sync",
    "status": "processing",
    "created_at": "2026-05-10 10:01:00"
  }
}
```

---

### 3.2 查询对口型任务状态

**功能**: 查询对口型合成进度和结果视频URL。

**API**: `GET /plugin_api_simple/query_status.php?task_id=LS_67890`

**认证**: Bearer Token 或 API Key

**响应（成功）**:
```json
{
  "success": true,
  "data": {
    "task_id": "LS_67890",
    "status": "success",
    "video_url": "https://www.aiom.com.cn/uploads/video/result.mp4",
    "created_at": "2026-05-10 10:01:00",
    "updated_at": "2026-05-10 10:03:00"
  }
}
```

**智能体轮询逻辑**:
```javascript
async function waitForLipSync(taskId, token, maxWait = 300) {
  for (let i = 0; i < maxWait / 5; i++) {
    await sleep(5000);
    const resp = await fetch(
      `https://www.aiom.com.cn/plugin_api_simple/query_status.php?task_id=${taskId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await resp.json();
    if (data.data.status === 'success') {
      return data.data.video_url;  // ← 返回对口型视频URL
    }
    if (data.data.status === 'failed') {
      throw new Error('对口型失败: ' + data.message);
    }
  }
  throw new Error('超时');
}
```

---

## 模块四：图像生成（Image2）

### 4.1 创建图像生成任务

**功能**: AI图像生成，支持文生图和图生图。

**API**: `POST /php/api_image_gen.php?action=generate`

**认证**: Bearer Token

**文生图请求体**:
```json
{
  "mode": "text2img",
  "prompt": "一只可爱的橘猫在花园里玩耍，阳光洒在身上，卡通风格，高清",
  "model": "image2",
  "size": "auto",
  "quantity": 1
}
```

**图生图请求体**:
```json
{
  "mode": "img2img",
  "prompt": "保持姿势和构图，改成水彩画风格",
  "model": "image2",
  "size": "auto",
  "quantity": 1,
  "images": [
    "https://example.com/reference.jpg"
  ]
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mode` | string | ✅ | `text2img` 或 `img2img` |
| `prompt` | string | ✅ | 图像描述文本 |
| `model` | string | ❌ | 模型名称，默认 `image2` |
| `size` | string | ❌ | 尺寸：`auto`/`square`/`landscape`/`portrait` |
| `quantity` | int | ❌ | 生成数量 1-4，默认 1 |
| `images` | array | ❌ | 图生图时的参考图URL数组 |

**响应**:
```json
{
  "success": true,
  "task_id": "260342195",
  "quantity": 1,
  "cost_amount": 0.29,
  "unit_price": 0.29,
  "balance_remaining": 9.71,
  "status": "pending",
  "message": "任务已创建，正在生成..."
}
```

**计费说明**:
- 生图按张扣费，默认 0.29元/张
- 生成失败自动退款
- 余额不足时返回 `need_recharge: true`

---

### 4.2 查询图像生成状态

**API**: `GET /php/api_image_gen.php?action=query&task_id=260342195`

**认证**: Bearer Token

**响应（成功）**:
```json
{
  "success": true,
  "status": "success",
  "task_id": "260342195",
  "images": [
    {
      "url": "https://example.com/generated_image.jpg",
      "thumbnail": "https://example.com/generated_image.jpg"
    }
  ],
  "cost": 0.003,
  "balance_remaining": 9.71
}
```

**智能体轮询逻辑**:
```javascript
async function waitForImage(taskId, token, maxWait = 120) {
  for (let i = 0; i < maxWait / 5; i++) {
    await sleep(5000);
    const resp = await fetch(
      `https://www.aiom.com.cn/php/api_image_gen.php?action=query&task_id=${taskId}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await resp.json();
    if (data.status === 'success') {
      return data.images.map(img => img.url);  // ← 返回图片URL数组
    }
    if (data.status === 'failed') {
      throw new Error('生图失败: ' + data.error);
    }
  }
  throw new Error('超时');
}
```

---

## 模块五：智能体工作流（完整自动化）

### 5.1 一键生成对口型视频（完整流程）

**功能**: 智能体只需提供文本，AIOM自动完成：找音色→合成语音→找视频→对口型。

**API**: `POST /php/agent_api.php`

**认证**: API Key 或 Bearer Token

**请求体**:
```json
{
  "task_type": "full_workflow",
  "content": "大家好，欢迎来到我们的店铺，今天给大家推荐一款超级好用的产品！",
  "voice_tag": "男声",
  "video_tag": "正面"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_type` | string | ❌ | `full_workflow`/`synthesize_only`/`lip_sync_only`，默认 `full_workflow` |
| `content` | string | ✅ | 要合成的文本内容 |
| `voice_tag` | string | ❌ | 音色关键词（如"男声/女声/客服"），自动匹配录音 |
| `video_tag` | string | ❌ | 视频关键词（如"正面/侧面"），自动匹配视频 |
| `recording_id` | int | ❌ | 直接指定录音ID（优先于voice_tag） |
| `video_id` | int | ❌ | 直接指定视频ID（优先于video_tag） |
| `audio_url` | string | ❌ | 直接提供音频URL（跳过语音合成） |

**响应**:
```json
{
  "success": true,
  "data": {
    "task_id": "AW_12345",
    "status": "processing",
    "message": "工作流已启动"
  }
}
```

**轮询查询**:
```http
GET /php/agent_api.php?task_id=AW_12345
X-API-Key: YOUR_API_KEY
```

**最终响应**:
```json
{
  "success": true,
  "data": {
    "task_id": "AW_12345",
    "status": "success",
    "video_url": "https://www.aiom.com.cn/uploads/video/final.mp4",
    "created_at": "2026-05-10 10:00:00",
    "updated_at": "2026-05-10 10:05:00"
  }
}
```

---

## 🧩 完整使用流程（智能体标准操作）

### 场景：用户要求"帮我生成一段带货视频"

#### 步骤1：获取用户Token
```javascript
const token = "从用户输入或数据库获取";
```

#### 步骤2：获取素材列表
```javascript
// 获取录音列表
const recordings = await fetch('https://www.aiom.com.cn/php/get_recordings.php', {
  headers: { Authorization: `Bearer ${token}` }
}).then(r => r.json());

// 获取视频列表
const videos = await fetch('https://www.aiom.com.cn/php/get_videos.php', {
  headers: { Authorization: `Bearer ${token}` }
}).then(r => r.json());
```

#### 步骤3：选择素材
```javascript
// 根据用户偏好选择（如"男声客服"风格）
const selectedRecording = recordings.recordings.find(r => 
  r.tags.includes('男声') && r.tags.includes('客服')
);

const selectedVideo = videos.videos.find(v => 
  v.tags.includes('正面')
);
```

#### 步骤4：调用工作流API
```javascript
const workflowResp = await fetch('https://www.aiom.com.cn/php/agent_api.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    task_type: 'full_workflow',
    content: '大家好，欢迎来到我们的店铺，今天给大家推荐一款超级好用的产品！',
    voice_tag: '男声',
    video_tag: '正面'
  })
});

const workflowData = await workflowResp.json();
const taskId = workflowData.data.task_id;
```

#### 步骤5：轮询等待结果
```javascript
const videoUrl = await waitForWorkflow(taskId, token);
// videoUrl = "https://www.aiom.com.cn/uploads/video/final.mp4"
```

#### 步骤6：返回结果给用户
```javascript
return {
  success: true,
  video_url: videoUrl,
  message: '视频生成完成！'
};
```

---

## 📊 API参考总览

| 功能 | 接口 | 方法 | 认证 |
|------|------|------|------|
| 注册 | `/php/register.php` | POST | 无 |
| 登录 | `/php/login.php` | POST | 无 |
| 获取录音 | `/php/get_recordings.php` | GET | Token |
| 获取视频 | `/php/get_videos.php` | GET | Token |
| 获取BGM | `/php/get_bgm_list.php` | GET | Token |
| 语音合成 | `/plugin_api_simple/voice_synthesis.php` | POST | Token |
| 查询任务 | `/plugin_api_simple/query_status.php` | GET | Token |
| 对口型 | `/plugin_api_simple/lip_sync.php` | POST | Token |
| 工作流 | `/php/agent_api.php` | POST/GET | API Key |
| 生图 | `/php/api_image_gen.php?action=generate` | POST | Token |
| 查询生图 | `/php/api_image_gen.php?action=query` | GET | Token |
| MCP SSE | `/mcp/sse` | GET | 无 |
| MCP消息 | `/mcp/messages` | POST | 无 |
| 健康检查 | `/health` | GET | 无 |

---

## 💰 计费与权限

### 图像生成计费
| 档位 | 单价（元/张） |
|------|--------------|
| guest（免费） | 0.50 |
| starter | 0.50 |
| popular | 0.38 |
| vip | 0.28 |

### 对口型计费
| 计费方式 | 价格 | 说明 |
|----------|------|------|
| 按秒计费 | **1.2元/分钟** | 按合成后的视频时长精确到秒扣费 |

**计费公式**：`费用 = (视频秒数 ÷ 60) × 1.2`

**示例**：
- 30秒视频：30 ÷ 60 × 1.2 = **0.60元**
- 60秒视频：60 ÷ 60 × 1.2 = **1.20元**
- 120秒视频：120 ÷ 60 × 1.2 = **2.40元**

**注意**：
- 按实际合成后的视频时长扣费
- 精度到秒，不足1秒按1秒计算
- 生成失败自动退款

### 余额查询
```http
GET /php/account.php
Authorization: Bearer TOKEN
```

---

## 🔒 安全说明

1. **Token安全**: 不要泄露用户Token
2. **HTTPS**: 所有请求必须使用HTTPS
3. **错误处理**: API调用失败时检查响应中的 `error` 字段
4. **频率限制**: 无严格限制，但请合理使用

---

## 📞 技术支持

- **官网**: https://www.aiom.com.cn
- **MCP端点**: https://www.aiom.com.cn/mcp/sse
- **文档**: 本文件
- **API文档**: https://www.aiom.com.cn/API_DOCS.md

---

## 🎯 智能体最佳实践

### 1. 缓存素材列表
```javascript
// 缓存录音和视频列表，避免重复请求
const cache = {
  recordings: null,
  videos: null,
  expiresAt: 0
};

async function getRecordings(token) {
  if (cache.recordings && Date.now() < cache.expiresAt) {
    return cache.recordings;
  }
  const data = await fetch('/php/get_recordings.php', {
    headers: { Authorization: `Bearer ${token}` }
  }).then(r => r.json());
  cache.recordings = data;
  cache.expiresAt = Date.now() + 3600000; // 1小时
  return data;
}
```

### 2. 异步任务轮询
```javascript
// 统一的任务等待函数
async function waitForTask(taskId, token, type = 'query', maxWait = 300) {
  const isImage = type === 'image';
  const baseUrl = isImage 
    ? '/php/api_image_gen.php' 
    : '/plugin_api_simple/query_status.php';
  
  for (let i = 0; i < maxWait / 5; i++) {
    await sleep(5000);
    const url = isImage 
      ? `${baseUrl}?action=query&task_id=${taskId}`
      : `${baseUrl}?task_id=${taskId}`;
    
    const resp = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` }
    });
    const data = await resp.json();
    
    const status = isImage ? data.status : data.data?.status;
    
    if (status === 'success') {
      return isImage ? data.images : data.data;
    }
    if (status === 'failed') {
      const errorMsg = isImage ? data.error : data.message;
      throw new Error('任务失败: ' + errorMsg);
    }
  }
  throw new Error('任务超时');
}
```

### 3. 错误重试
```javascript
async function retryableCall(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(2000 * (i + 1)); // 指数退避
    }
  }
}
```

---

## 📝 更新日志

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 2.0 | 2026-05-10 | 新增Image2生图API、工作流API、MCP支持 |
| 1.0 | 2026-04-01 | 初始版本，支持语音合成和对口型 |

---

**AIOM 智能创作平台 v2.0**  
让每个小商家都能用AI生成专业级短视频！