动画视频制作

Canvas动画智能体 API 文档

概述

Canvas动画智能体是一个基于AI的Canvas动画生成系统，能够根据用户描述生成交互式Canvas动画，并支持WebM视频录制和导出功能。系统提供完整的项目管理和部署能力。

基础信息

  • 基础路径: /rtagent/canvas_agent_script_c
  • 数据目录: /home/agents/canvas_agent_script_c/data/
    • projects/ - 项目存储目录
    • cache/ - 缓存目录
    • deployments/ - 部署记录目录
  • 响应格式: JSON
  • 错误处理: 所有API返回{ret: boolean, msg: string, data?: any}格式

API端点

1. 生成Canvas动画

端点: POST /rtagent/canvas_agent_script_c/generate

功能: 根据用户描述生成Canvas动画代码，包含动画和WebM录制功能

请求参数:

参数名 类型 必填 默认值 说明
user_id string 是 - 用户唯一标识符
prompt string 是 - 动画描述文本
title string 否 "Canvas动画" 动画标题

请求示例:

{
  "user_id": "user_123",
  "prompt": "生成一个粒子系统动画，粒子会跟随鼠标移动",
  "title": "粒子跟随动画"
}

响应数据结构:

{
  "ret": true,
  "msg": "Canvas动画生成成功",
  "data": {
    "project_id": "canvas_1700000000000_abc123def",
    "title": "粒子跟随动画",
    "status": "generated",
    "created_at": "2024-01-01T12:00:00.000Z",
    "validation": {
      "isValid": true,
      "errors": []
    },
    "html_preview": "<!DOCTYPE html><html>...（前500字符）"
  }
}

字段说明:

  • project_id: 项目唯一标识符，格式为canvas_时间戳_随机字符串
  • status: 项目状态，可能值：generated、deployed
  • validation: 代码验证结果
    • isValid: 验证是否通过
    • errors: 验证错误信息数组
  • html_preview: HTML代码预览（前500字符）

错误响应:

{
  "ret": false,
  "msg": "用户ID和提示语不能为空",
  "stack": "错误堆栈信息（仅开发环境）"
}

2. 导出WebM视频

端点: POST /rtagent/canvas_agent_script_c/export

功能: 配置视频导出参数（实际导出在浏览器端执行）

请求参数:

参数名 类型 必填 默认值 说明
project_id string 是 - 项目ID
duration number 否 5000 录制时长（毫秒）

请求示例:

{
  "project_id": "canvas_1700000000000_abc123def",
  "duration": 10000
}

响应数据结构:

{
  "ret": true,
  "msg": "视频导出配置已生成",
  "data": {
    "project_id": "canvas_1700000000000_abc123def",
    "export_config": {
      "duration": 10000,
      "format": "webm",
      "codec": "vp9",
      "bitrate": "2500000",
      "fps": 30
    },
    "instructions": "请在浏览器中打开生成的页面，使用页面上的录制和导出功能"
  }
}

字段说明:

  • export_config: 视频导出配置
    • duration: 录制时长（毫秒）
    • format: 视频格式（固定为webm）
    • codec: 视频编码器（固定为vp9）
    • bitrate: 比特率（2500000 bps）
    • fps: 帧率（30帧/秒）

3. 部署项目

端点: POST /rtagent/canvas_agent_script_c/deploy

功能: 将生成的Canvas动画项目部署为可访问的Web应用

请求参数:

参数名 类型 必填 默认值 说明
project_id string 是 - 项目ID
app_name string 否 canvas_{project_id} 应用名称
app_title string 否 项目标题 应用显示标题

请求示例:

{
  "project_id": "canvas_1700000000000_abc123def",
  "app_name": "my-particle-animation",
  "app_title": "我的粒子动画"
}

响应数据结构:

{
  "ret": true,
  "msg": "部署成功",
  "data": {
    "project_id": "canvas_1700000000000_abc123def",
    "app_url": "https://deployed-app.example.com/my-particle-animation",
    "app_name": "my-particle-animation",
    "deployment_time": "2024-01-01T12:30:00.000Z",
    "deployment_id": "1700000000000"
  }
}

字段说明:

  • app_url: 部署后的应用访问URL
  • deployment_id: 部署记录ID（时间戳）
  • deployment_time: 部署时间

4. 列出项目

端点: GET /rtagent/canvas_agent_script_c/list

功能: 分页列出用户的项目列表

请求参数:

参数名 类型 必填 默认值 说明
user_id string 否 - 用户ID（不传则返回所有项目）
page number 否 1 页码
limit number 否 20 每页数量

请求示例:

{
  "user_id": "user_123",
  "page": 1,
  "limit": 10
}

响应数据结构:

{
  "ret": true,
  "data": {
    "projects": [
      {
        "project_id": "canvas_1700000000000_abc123def",
        "user_id": "user_123",
        "prompt": "生成一个粒子系统动画",
        "title": "粒子跟随动画",
        "created_at": "2024-01-01T12:00:00.000Z",
        "updated_at": "2024-01-01T12:00:00.000Z",
        "status": "generated",
        "metadata": {
          "validation": {
            "isValid": true,
            "errors": []
          },
          "has_webm": true,
          "has_capture_stream": true,
          "has_animation": true
        }
      }
    ],
    "statistics": {
      "total_projects": 15,
      "total_pages": 2,
      "current_page": 1,
      "limit": 10,
      "generated_projects": 10,
      "deployed_projects": 5,
      "user_projects": 15
    }
  }
}

字段说明:

  • projects: 项目列表（不包含HTML代码等大字段）
  • statistics: 统计信息
    • total_projects: 总项目数
    • total_pages: 总页数
    • current_page: 当前页码
    • generated_projects: 已生成项目数
    • deployed_projects: 已部署项目数
    • user_projects: 用户项目数（指定user_id时）

5. 加载项目详情

端点: GET /rtagent/canvas_agent_script_c/load

功能: 加载指定项目的完整信息，包括HTML代码

请求参数:

参数名 类型 必填 默认值 说明
project_id string 是 - 项目ID

请求示例:

{
  "project_id": "canvas_1700000000000_abc123def"
}

响应数据结构:

{
  "ret": true,
  "msg": "项目加载成功",
  "data": {
    "project_id": "canvas_1700000000000_abc123def",
    "user_id": "user_123",
    "prompt": "生成一个粒子系统动画",
    "title": "粒子跟随动画",
    "html_code": "<!DOCTYPE html>...完整HTML代码...",
    "canvas_code": "const canvas = ...动画JavaScript代码...",
    "recorder_code": "class CanvasRecorder {...录制器代码...}",
    "created_at": "2024-01-01T12:00:00.000Z",
    "updated_at": "2024-01-01T12:00:00.000Z",
    "status": "generated",
    "session_id": "session_abc123",
    "metadata": {
      "validation": {
        "isValid": true,
        "errors": []
      },
      "has_webm": true,
      "has_capture_stream": true,
      "has_animation": true
    }
  }
}

字段说明:

  • html_code: 完整的HTML页面代码
  • canvas_code: Canvas动画JavaScript代码
  • recorder_code: WebM录制器JavaScript代码
  • session_id: AI会话ID（用于继续对话）

6. 预览动画

端点: GET /rtagent/canvas_script_c/preview

功能: 获取动画的HTML代码用于预览

请求参数:

参数名 类型 必填 默认值 说明
project_id string 是 - 项目ID

响应数据结构:

{
  "ret": true,
  "msg": "动画预览",
  "data": {
    "project_id": "canvas_1700000000000_abc123def",
    "title": "粒子跟随动画",
    "html_code": "<!DOCTYPE html>...完整HTML代码...",
    "created_at": "2024-01-01T12:00:00.000Z",
    "status": "generated"
  }
}

数据结构说明

项目数据结构 (Project)

{
  project_id: string,          // 项目唯一标识
  user_id: string,            // 用户ID
  prompt: string,             // 用户输入的描述
  title: string,              // 动画标题
  html_code: string,          // 完整HTML代码
  canvas_code: string,        // Canvas动画代码
  recorder_code: string,      // 录制器代码
  created_at: string,         // 创建时间(ISO格式)
  updated_at: string,         // 更新时间(ISO格式)
  status: 'generated' | 'deployed',  // 项目状态
  session_id: string,         // AI会话ID
  metadata: {                 // 元数据
    validation: {             // 验证结果
      isValid: boolean,
      errors: string[]
    },
    has_webm: boolean,        // 是否包含WebM支持
    has_capture_stream: boolean, // 是否包含captureStream
    has_animation: boolean    // 是否包含动画循环
  },
  deployment_url?: string,    // 部署URL（仅当已部署）
  deployed_at?: string,       // 部署时间（仅当已部署）
  app_name?: string           // 应用名称（仅当已部署）
}

部署记录结构 (Deployment)

{
  project_id: string,         // 项目ID
  deployment_id: string,      // 部署记录ID（时间戳）
  app_url: string,            // 应用URL
  app_name: string,           // 应用名称
  deployed_at: string,        // 部署时间
  result: any                 // 部署结果详情
}

错误码说明

错误类型 HTTP状态码 说明
MISSING_PARAMETERS 400 缺少必要参数
PROJECT_NOT_FOUND 404 项目不存在或已过期
GENERATION_FAILED 500 生成动画失败
DEPLOYMENT_FAILED 500 部署失败
VALIDATION_FAILED 400 代码验证失败
INTERNAL_ERROR 500 内部服务器错误

使用流程

  1. 生成动画: 调用/generate接口，传入用户描述
  2. 预览动画: 调用/preview或/load获取HTML代码
  3. 部署项目: 调用/deploy将动画部署为Web应用
  4. 导出视频: 在部署的应用中使用页面功能录制和导出WebM视频
  5. 管理项目: 使用/list查看项目列表，/load查看详情

注意事项

  1. 视频导出: 实际视频导出功能需要在浏览器端执行，API只提供配置信息
  2. 代码验证: 所有生成的代码都会经过验证，确保包含必要的Canvas和WebM功能
  3. 会话管理: 每个项目关联一个AI会话，可用于继续生成或修改代码
  4. 文件存储: 所有项目数据存储在/home/agents/canvas_agent_script_c/data/目录下
  5. 依赖要求: 需要jszip模块用于部署时的ZIP打包

示例调用序列

# 1. 生成动画
curl -X POST http://localhost:3000/rtagent/canvas_agent_script_c/generate \
  -H "Content-Type: application/json" \
  -d '{"user_id":"test_user","prompt":"生成星空背景的粒子动画","title":"星空粒子"}'

# 2. 列出项目
curl -X GET "http://localhost:3000/rtagent/canvas_agent_script_c/list?user_id=test_user&page=1&limit=10"

# 3. 部署项目
curl -X POST http://localhost:3000/rtagent/canvas_agent_script_c/deploy \
  -H "Content-Type: application/json" \
  -d '{"project_id":"canvas_1700000000000_abc123def","app_name":"star-particles"}'