GEN_VIDEO 接口开发完成报告

📄 GEN_VIDEO_COMPLETION_REPORT.md 🕒 8/10/2025, 6:53:13 PM 📏 10KB

GEN_VIDEO 接口开发完成报告

📋 接口概述

接口名称: gen_video
功能描述: 云渲染视频，接收草稿链接并提交到外部渲染服务生成视频
开发状态: ✅ 已完成并测试通过
开发时间: 2025年8月1日

🎯 功能实现

核心功能 ✅

技术特性 ✅

📝 接口规格

请求参数

{
  "api_token": "1f0a1709-fa9e-4bf3-8180-6371b05f5fd6",  // 必填：API访问令牌(UUID格式)
  "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-03-01/draft/98598661-8583-4baa-89d1-1e27c688d695.json"  // 必填：草稿文件URL
}

响应格式

{
  "status": "success",
  "message": "视频渲染任务提交成功",
  "data": {
    "code": 0,
    "message": "Task submitted successfully",
    "task_id": "render_task_12345678",
    "estimated_time": 120,
    "render_status": "queued",
    "tip": "剪映小助手个人中心也可以查看状态和视频链接，计费详情请查看：https://www.51aigc.cc/#/plugins"
  }
}

🧪 测试结果

1. 基本功能测试 ✅

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "1f0a1709-fa9e-4bf3-8180-6371b05f5fd6",
    "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-03-01/draft/98598661-8583-4baa-89d1-1e27c688d695.json"
  }'

测试结果: ✅ 成功

2. 参数验证测试 ✅

无效UUID格式验证

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video \
  -H "Content-Type: application/json" \
  -d '{"api_token": "invalid-token", "draft_url": "https://example.com/draft.json"}'

结果: ✅ 正确返回 "api_token must be a valid UUID format"

空参数验证

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video \
  -H "Content-Type: application/json" \
  -d '{"api_token": "", "draft_url": ""}'

结果: ✅ 正确返回 "api_token是必填项", "draft_url是必填项"

3. URL格式处理测试 ✅

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "1f0a1709-fa9e-4bf3-8180-6371b05f5fd6",
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/test.json"
  }'

结果: ✅ 成功

🏗️ 技术实现

文件结构 ✅

核心算法 ✅

// 视频渲染处理流程
1. 参数验证：validateVideoRender(renderConfig)
2. 初始化动态导入：initDynamicImports() 确保fetch可用
3. URL清理：移除剪映链接前缀，提取实际草稿URL
4. 调用外部API：POST https://ts-api.fyshark.com/api/submit_video_render_task
5. 响应处理：添加提示信息并返回结果

验证机制 ✅

错误处理 ✅

📊 性能指标

处理效率 ✅

支持能力 ✅

🔄 工作流程

graph TD
    A[接收请求] --> B[参数验证]
    B --> C{验证通过?}
    C -->|否| D[返回400错误]
    C -->|是| E[初始化动态导入]
    E --> F[清理draft_url]
    F --> G[构建API请求]
    G --> H[调用外部渲染API]
    H --> I{API调用成功?}
    I -->|否| J[处理网络错误]
    I -->|是| K[解析API响应]
    K --> L[添加提示信息]
    L --> M[返回成功响应]
    J --> N[返回相应错误状态码]

🚀 使用示例

JavaScript 示例

const generateVideo = async (apiToken, draftUrl) => {
  const response = await fetch('/api/drafts/gen_video', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      api_token: apiToken,
      draft_url: draftUrl
    })
  });
  
  const result = await response.json();
  if (result.status === 'success') {
    return result.data;
  }
  throw new Error(result.message);
};

// 使用示例
const result = await generateVideo(
  "1f0a1709-fa9e-4bf3-8180-6371b05f5fd6",
  "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-03-01/draft/98598661-8583-4baa-89d1-1e27c688d695.json"
);
console.log('任务ID:', result.task_id);

Python 示例

import requests

def generate_video(api_token, draft_url):
    response = requests.post(
        'https://jy-api.fyshark.com/api/drafts/gen_video',
        headers={'Content-Type': 'application/json'},
        json={
            'api_token': api_token,
            'draft_url': draft_url
        }
    )
    
    result = response.json()
    if result['status'] == 'success':
        return result['data']
    raise Exception(result['message'])

# 使用示例
result = generate_video(
    "1f0a1709-fa9e-4bf3-8180-6371b05f5fd6",
    "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-03-01/draft/98598661-8583-4baa-89d1-1e27c688d695.json"
)
print(f"任务ID: {result['task_id']}")

📖 应用场景

自动化视频制作 🎬

内容创作平台 📱

企业应用 🏢

教育培训 📚

⚠️ 注意事项

使用限制

  1. API令牌: 必须使用有效的UUID格式令牌
  2. 草稿文件: 必须是可访问的JSON格式文件
  3. 网络连接: 需要稳定的网络连接访问外部渲染服务
  4. 计费规则: 每次渲染任务都会产生费用

最佳实践

  1. 令牌安全: 妥善保管API令牌，避免泄露
  2. 错误重试: 实现自动重试机制处理网络波动
  3. 状态监控: 定期查询任务状态确认渲染进度
  4. 成本控制: 合理控制渲染任务数量避免超支

🔗 相关接口

草稿管理系列

内容编辑系列

样式设计系列

🚀 最佳实践

完整工作流程

// ✅ 推荐：完整的视频制作和渲染流程
const createAndRenderVideo = async (apiToken) => {
  try {
    // 1. 创建草稿
    const draft = await createDraft({ title: "我的视频" });
    
    // 2. 添加内容
    await addImages(draft.url, imageData);
    await addAudios(draft.url, audioData);
    await addCaptions(draft.url, captionData);
    await addEffects(draft.url, effectData);
    
    // 3. 提交渲染
    const renderResult = await generateVideo(apiToken, draft.url);
    
    console.log('渲染任务提交成功:', {
      taskId: renderResult.task_id,
      estimatedTime: renderResult.estimated_time
    });
    
    return renderResult;
  } catch (error) {
    console.error('视频制作流程失败:', error.message);
    throw error;
  }
};

错误处理和重试

// ✅ 推荐：带重试机制的渲染
const renderWithRetry = async (apiToken, draftUrl, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await generateVideo(apiToken, draftUrl);
      return result;
    } catch (error) {
      console.log(`渲染尝试 ${i + 1} 失败:`, error.message);
      
      if (i === maxRetries - 1) {
        throw new Error(`渲染失败，已重试 ${maxRetries} 次: ${error.message}`);
      }
      
      // 指数退避重试
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
};

批量渲染管理

// ✅ 推荐：批量渲染管理
const batchRender = async (tasks, apiToken, concurrency = 3) => {
  const results = [];
  
  // 分批处理避免过载
  for (let i = 0; i < tasks.length; i += concurrency) {
    const batch = tasks.slice(i, i + concurrency);
    
    const batchPromises = batch.map(async (task) => {
      try {
        const result = await generateVideo(apiToken, task.draftUrl);
        return { success: true, task, result };
      } catch (error) {
        return { success: false, task, error: error.message };
      }
    });
    
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
    
    // 批次间延迟
    if (i + concurrency < tasks.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  return results;
};

✅ 开发总结

开发状态: 🎉 完全成功

完成情况

技术亮点

  1. 智能URL处理: 自动识别和处理剪映链接格式
  2. 严格参数验证: UUID格式验证和完整的输入检查
  3. 可靠网络请求: 使用node-fetch确保HTTP请求稳定性
  4. 完善错误处理: 分类处理各种错误情况并返回友好提示
  5. 标准化响应: 统一的API响应格式和状态码

关键技术

开发者: JY API Team
完成时间: 2025年8月1日
接口状态: ✅ 生产就绪
文档版本: v1.0.0
外部服务: https://ts-api.fyshark.com/api/submit_video_render_task

📚 文档中心 🏠 API首页
↑