duo-video-api

name	duo-video API 接口
description	帮助用户使用 duo-video-api 模块的 HTTP 接口创建视频工程和视频创作任务。当需要通过 REST API 进行视频项目管理和任务调度时使用此技能。
compatibility	["rest-api","http","video-management"]

duo-video API 接口

功能

• 通过 HTTP 接口创建视频项目
• 添加各种类型的素材到视频项目
• 管理视频创作任务
• 查询项目和任务状态
• 构建视频并获取任务ID

API 基础信息

• 基础URL: http://localhost:8080 (默认)
• 内容类型: application/json
• 响应格式:

{
  "code": 0,           // 0 表示成功，非 0 表示失败
  "msg": "success",    // 一般在 code!=0时，会有值，表示错误原因
  "data": { ... }      // 具体响应数据
}

核心接口

1. 创建视频项目

POST /api/video

请求参数:

{
  "projectId": 123456789,      // 可选，不传则自动生成
  "projectName": "我的视频",    // 可选，默认使用 projectId
  "width": 1080,               // 可选，默认 1080
  "height": 1920,              // 可选，默认 1920
  "test": true                 // 可选，是否为测试模式
}

响应示例:

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 123456789,
    "projectName": "我的视频",
    "width": 1080,
    "height": 1920,
    "test": true,
    "scripts": [],
    "materials": []
  }
}

2. 设置全局文本样式

POST /api/project/global-style

请求参数:

{
  "projectId": 123456789,
  "styleId": 296653948753219540,
  "textStyle": {
    "fontSize": 28,
    "bold": true,
    "italic": true,
    "textAlign": 1,
    "fontName": "抖音美好体",
    "fillColor": "#FFFF00",
    "strokeColor": "#FF0000",
    "strokeWidth": 10
  },
  "globalKeywordStyle": true    // 是否设为全局关键词样式
}

3. 添加图片素材

POST /api/project/image

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,             // 分镜索引，默认 0
  "imageId": 535010997887571096,
  "imageUrl": "https://example.com/image.png",
  "startTime": 3500,            // 开始时间（毫秒）
  "duration": 3000,             // 持续时间（毫秒）
  "layoutIndex": 1000,          // 图层索引
  "zoomX": 7500,                // X 轴缩放（万分比）
  "zoomY": 7500,                // Y 轴缩放（万分比）
  "positionX": 0,               // X 轴位置
  "positionY": -1512,           // Y 轴位置
  "rotate": -90,                // 旋转角度
  "visible": true,              // 是否可见
  "horizontal": true,           // 水平翻转
  "vertical": true              // 垂直翻转
}

4. 添加视频素材（支持绿幕和蒙版）

POST /api/project/video

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "videoId": 535010997887571021,
  "videoUrl": "https://example.com/video.mp4",
  "startTime": 0,
  "duration": 3000,
  "materialStart": 5000,        // 素材开始位置（毫秒）
  "materialTimeStart": 0,       // 素材时间范围开始（毫秒）
  "materialTimeEnd": 14264,     // 素材时间范围结束（毫秒）
  "layoutIndex": 1000,
  "speed": 100,                 // 播放速度（百分比）
  "zoomX": 10000,
  "zoomY": 10000,
  "rotate": 90,
  "visible": true,
  "horizontal": true,
  "volume": 0,                  // 音量（-100 到 100）
  "transitionId": 270404457990455297,  // 转场特效 ID
  "transitionDuration": 1000,          // 转场持续时间
  "greenBackground": {          // 绿幕背景（可选）
    "greenScreenId": 535010997887571022,
    "greenScreenUrl": "https://example.com/green.png",
    "chromaColor": "#4e8a1fff",
    "chromaStrength": 20,
    "chromaShadow": 10,
    "chromaHighlight": 10
  },
  "mask": {                     // 蒙版（可选）
    "maskId": 270415264124764161,
    "feather": 5,
    "rotation": 90,
    "width": 0.5,
    "height": 0.28,
    "centerX": 0.07,
    "centerY": 0.25,
    "pointX": 400,
    "pointY": 400
  }
}

5. 添加音频素材

POST /api/project/audio

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "audioId": 535010997887571025,
  "audioUrl": "https://example.com/audio.mp3",
  "startTime": 0,
  "duration": 8000,
  "materialTimeStart": 170,
  "materialTimeEnd": 126869,
  "materialStart": 10000,
  "layoutIndex": 1000,
  "speed": 100,
  "visible": true,
  "volume": -50
}

6. 添加文本/字幕

POST /api/project/text

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "text": "测试中文字幕",
  "startTime": 10,
  "duration": 1990,
  "layoutIndex": 1000,
  "positionX": 0,
  "positionY": -1000,
  "rotate": 0,
  "asSubtitle": true,           // 是否作为字幕
  "styleId": 296653948753219540, // 引用全局样式 ID（可选）
  "style": {                    // 自定义样式（可选）
    "fontSize": 14,
    "bold": false,
    "italic": false,
    "textAlign": 1,
    "fontName": "微软雅黑",
    "fillColor": "#FFFFFF",
    "strokeColor": "#FF0000",
    "strokeWidth": 10
  },
  "wordStyles": [               // 逐字样式（可选）
    {
      "startIndex": 2,
      "length": 2,
      "fontSize": 16,
      "fillColor": "#00FFFF",
      "strokeWidth": 20,
      "strokeColor": "#0000FF"
    },
    {
      "startIndex": 3,
      "length": 2,
      "styleId": 296653948753219540,
      "fontSize": 18,
      "flowerId": 270413717936603137  // 花字 ID
    }
  ]
}

7. 添加文本模板

POST /api/project/text-template

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "templateId": 270414005699805185,
  "texts": ["非", "常", "棒", "duoec.com"],
  "startTime": 2001,
  "duration": 999,
  "layoutIndex": 1000,
  "zoomX": 5000,
  "zoomY": 5000,
  "positionX": 0,
  "positionY": 1400
}

8. 添加贴纸

POST /api/project/sticker

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "stickerId": 270402997699280897,
  "startTime": 1500,
  "duration": 3000,
  "zoomX": 5000,
  "zoomY": 5000,
  "positionX": 500,
  "positionY": 0,
  "rotate": -45
}

9. 添加画面特效

POST /api/project/video-effect

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "effectId": 270464037793497089,
  "startTime": 5000,
  "duration": 3000
}

10. 添加人脸特效

POST /api/project/face-effect

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "effectId": 270464033541718017,
  "startTime": 1500,
  "duration": 1000
}

11. 添加音效

POST /api/project/sound

请求参数:

{
  "projectId": 123456789,
  "scriptIndex": 0,
  "soundId": 270464042140893185,
  "startTime": 1000,
  "duration": 3000
}

12. 构建视频

POST /api/project/build

请求参数:

{
  "id": 123456789,
  "projectName": "我的视频",
  "width": 1080,
  "height": 1920,
  "scripts": [...],
  "materials": [...]
}

响应示例:

{
  "code": 0,
  "msg": "success",
  "data": 987654321  // 视频构建任务ID
}

完整示例

使用 curl 创建一个完整的视频项目：

# 1. 创建项目
curl -X POST http://localhost:8080/api/video \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 123456789,
    "projectName": "我的第一个视频",
    "width": 1080,
    "height": 1920,
    "test": true
  }'

# 2. 添加视频素材
curl -X POST http://localhost:8080/api/project/video \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 123456789,
    "videoId": 535010997887571021,
    "videoUrl": "https://api.duoec.com/public/video/535010997887571021.mp4",
    "startTime": 0,
    "duration": 3000,
    "zoomX": 10000,
    "zoomY": 10000
  }'

# 3. 添加文本
curl -X POST http://localhost:8080/api/project/text \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 123456789,
    "text": "Hello World",
    "startTime": 0,
    "duration": 3000,
    "positionY": -800
  }'

# 4. 构建视频
curl -X POST http://localhost:8080/api/project/build \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123456789,
    "projectName": "我的第一个视频",
    "width": 1080,
    "height": 1920,
    "scripts": [...],
    "materials": [...]
  }'

API 特性

• 链式操作: 每个接口返回完整的 VideoProject，可以连续调用
• 自动保存: 每次操作后自动保存项目状态
• 参数验证: 自动验证必填参数，返回友好的错误提示
• 灵活配置: 所有可选参数都有合理的默认值
• 完整功能: 支持所有 Builder 模式的功能，包括绿幕、蒙版、转场等高级特性

错误处理

• 检查参数完整性（如项目ID、素材ID等）
• 验证素材URL的有效性
• 确保时间范围不冲突
• 检查素材类型与接口的匹配性