openclaw-voc-skill/openclaw-skills/video-creation/quickly-video-create/api-config.json

{
  "name": "quickly-video-create",
  "displayName": "一键成片 - 创建生成任务",
  "description": "调用 Quickly 开放平台，基于图片/视频素材一键生成短视频。传入素材URL列表和关键词，返回 task_id，通过 quickly-video-query 轮询获取视频下载链接。",
  "category": "video-creation",
  "version": "1.0.0",
  "endpoint": {
    "method": "POST",
    "url": "https://server.fmode.cn/api/functions/cut/onemerge",
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "parameters": {
    "type": "object",
    "required": ["material_list", "tags", "proportion", "video_duration", "pre_id"],
    "properties": {
      "material_list": {
        "type": "array",
        "description": "素材列表，每项包含 type（pic|video）和 value（公网可访问URL）。图片支持 jpg/jpeg/png/gif，视频支持 mp4/webm。webp/非ASCII URL 需先转换，见 materialFormatRules。",
        "items": {
          "type": "object",
          "required": ["type", "value"],
          "properties": {
            "type": {
              "type": "string",
              "enum": ["pic", "video"],
              "description": "素材类型：pic=图片，video=视频"
            },
            "value": {
              "type": "string",
              "description": "素材的公网可访问URL，必须为纯ASCII字符，格式为 jpg/jpeg/png/gif（图片）或 mp4/webm（视频）"
            }
          }
        },
        "minItems": 1,
        "maxItems": 50,
        "recommended": "建议 5~15 个素材，效果最佳"
      },
      "tags": {
        "type": "string",
        "description": "逗号分隔的关键词，描述视频主题内容，由调用方根据业务场景自行提供",
        "example": "推拉门,极简风格,铝合金,隔音"
      },
      "proportion": {
        "type": "string",
        "enum": ["9:16", "3:4", "1:1"],
        "description": "视频比例：9:16=竖屏（1080×1920，抖音/快手主流），3:4=竖屏宽（900×1200），1:1=方形（1080×1080）",
        "default": "9:16"
      },
      "video_duration": {
        "type": "object",
        "description": "视频时长范围（秒）",
        "required": ["min", "max"],
        "properties": {
          "min": {
            "type": "integer",
            "enum": [5, 10, 15, 20, 25],
            "description": "最短时长（秒）",
            "default": 10
          },
          "max": {
            "type": "integer",
            "enum": [10, 15, 20, 25, 30],
            "description": "最长时长（秒）",
            "default": 20
          }
        }
      },
      "pre_id": {
        "type": "string",
        "description": "预定视频ID，纯数字格式，多个视频用逗号分隔（如 '1711234567890' 或 '1711234567890,1711234567891'）。使用 Date.now() 生成基础ID，每个视频递增1。",
        "example": "1711234567890"
      },
      "compose_number": {
        "type": "integer",
        "description": "生成视频数量，1~50",
        "default": 1,
        "minimum": 1,
        "maximum": 50
      },
      "ai_voice": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否开启 AI 配音（0=关闭，1=开启）",
        "default": 1
      },
      "ai_bgm": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否开启 AI 背景音乐（0=关闭，1=开启）",
        "default": 1
      },
      "ai_flower": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否开启 AI 特效转场（0=关闭，1=开启）",
        "default": 1
      },
      "ai_subtitle": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否开启 AI 字幕（0=关闭，1=开启）",
        "default": 0
      },
      "original_voice": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否保留视频素材原始音频（0=关闭，1=开启）",
        "default": 0
      }
    }
  },
  "materialFormatRules": {
    "supportedImageFormats": ["jpg", "jpeg", "png", "gif"],
    "supportedVideoFormats": ["mp4", "webm"],
    "unsupportedImageFormats": ["webp", "heic", "bmp", "tiff"],
    "unsupportedVideoFormats": ["mov", "avi", "mkv", "flv", "wmv"],
    "conversionRules": [
      {
        "trigger": "图片格式为 webp 或不在支持列表中",
        "solution": "通过浏览器 Canvas API 加载图片 → 导出为 JPEG (quality=0.9) → 上传至公网可访问的 CDN → 使用返回的新 URL",
        "uploadPrefix": "ai-video/converted/"
      },
      {
        "trigger": "URL 含非ASCII字符（中文文件名、特殊符号等）",
        "solution": "decodeURIComponent(url) 检测到非ASCII字符后，重新下载并上传 CDN 获取干净 URL",
        "uploadPrefix": "ai-video/image/"
      },
      {
        "trigger": "本地上传文件",
        "solution": "直接上传 CDN，图片前缀 ai-video/image/，视频前缀 ai-video/video/"
      },
      {
        "trigger": "视频格式不支持（mov/avi等）",
        "solution": "跳过该素材，提示用户转换为 mp4 后重新上传"
      }
    ],
    "cdnUpload": {
      "note": "所有素材需上传至国内可达的公网 CDN（如七牛、阿里云OSS），确保返回纯 ASCII URL。Quickly 服务器在国内，无法访问境外CDN，否则任务静默失败。"
    }
  },
  "requestTransform": {
    "description": "通过 server.fmode.cn 中转：将业务参数包装为 relay 请求，中转服务负责签名并调用 Quickly API",
    "body": {
      "action": "relay",
      "relayData": "JSON.stringify({ apiPath: '/v2/video/vlog/create', apiBody: {业务参数}, appKey: '{{appKey}}', timestamp: '{{timestamp}}', sign: 'MD5(timestamp#appSecret)' })"
    },
    "signGeneration": {
      "step1": "timestamp = Date.now().toString()",
      "step2": "signStr = timestamp + '#' + appSecret  // 直接使用原始字符串，不做base64解码",
      "step3": "sign = MD5(signStr).toLowerCase() [32位小写]"
    }
  },
  "response": {
    "type": "object",
    "description": "Quickly API 返回结果",
    "properties": {
      "code": {
        "type": "integer",
        "description": "0 或 200 表示成功，其他值表示错误"
      },
      "message": {
        "type": "string",
        "description": "响应描述信息"
      },
      "data": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "任务ID，传入 quickly-video-query 进行轮询查询"
          }
        }
      },
      "request_id": {
        "type": "string",
        "description": "请求唯一ID，用于联系 Quickly 客服排查问题"
      }
    }
  },
  "pollingConfig": {
    "description": "获取 task_id 后调用 quickly-video-query 轮询视频生成结果",
    "interval": 15000,
    "maxAttempts": 40
  },
  "usageExamples": [
    {
      "name": "图片素材生成竖屏短视频（9:16）",
      "description": "传入图片和视频素材，生成9:16竖屏短视频，适合抖音/快手发布",
      "input": {
        "material_list": [
          { "type": "pic", "value": "https://cdn.example.com/images/img1.jpg" },
          { "type": "pic", "value": "https://cdn.example.com/images/img2.jpg" },
          { "type": "pic", "value": "https://cdn.example.com/images/img3.jpg" },
          { "type": "video", "value": "https://cdn.example.com/videos/clip1.mp4" }
        ],
        "tags": "推拉门,极简风格,铝合金,隔音,全屋定制",
        "proportion": "9:16",
        "video_duration": { "min": 10, "max": 20 },
        "pre_id": "1711234567890",
        "compose_number": 3,
        "ai_voice": 1,
        "ai_bgm": 1,
        "ai_flower": 1,
        "ai_subtitle": 0
      },
      "expectedOutput": {
        "code": 0,
        "data": { "task_id": "987654321" }
      }
    },
    {
      "name": "图片素材生成方形视频（1:1）",
      "description": "生成1:1方形视频，适合朋友圈/公众号发布",
      "input": {
        "material_list": [
          { "type": "pic", "value": "https://cdn.example.com/images/img1.jpg" },
          { "type": "pic", "value": "https://cdn.example.com/images/img2.jpg" }
        ],
        "tags": "全屋定制,整体家装,收纳设计",
        "proportion": "1:1",
        "video_duration": { "min": 10, "max": 15 },
        "pre_id": "1711234567900",
        "compose_number": 1,
        "ai_voice": 1,
        "ai_bgm": 1,
        "ai_subtitle": 1
      }
    }
  ],
  "errorHandling": {
    "apiErrors": [
      { "code": "非0/200", "action": "抛出错误，提示用户检查素材格式和网络" },
      { "code": "素材URL不可访问", "action": "Quickly API 会在回调中返回 error_msg，前端需处理 success=false 的回调" }
    ],
    "materialErrors": [
      { "condition": "所有素材转换失败", "action": "中止生成，提示'没有可用的素材，请添加 JPG/PNG 图片或 MP4 视频后重试'" },
      { "condition": "有效素材列表为空", "action": "提前退出，不调用API" }
    ]
  },
  "timeout": 30000,
  "retry": {
    "maxAttempts": 2,
    "delay": 2000,
    "backoffMultiplier": 2
  }
}