GEN_VIDEO_STATUS 接口开发完成报告

📄 GEN_VIDEO_STATUS_COMPLETION_REPORT.md 🕒 8/10/2025, 6:54:09 PM 📏 10KB

GEN_VIDEO_STATUS 接口开发完成报告

📋 接口概述

接口名称: gen_video_status
功能描述: 查询视频草稿的渲染状态，获取渲染进度和结果信息
开发状态: ✅ 已完成并测试通过
开发时间: 2025年8月1日

🎯 功能实现

核心功能 ✅

技术特性 ✅

📝 接口规格

请求参数

{
  "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json"  // 必填：草稿文件URL
}

响应格式

{
  "status": "success",
  "message": "视频状态查询成功",
  "data": {
    "code": 200,
    "msg": "获取成功",
    "data": {
      "id": 316008,
      "user_id": 245769,
      "dayid": "2025-05-16",
      "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json",
      "video_url": "",
      "zip_url": "",
      "draft_id": "0b3de2f7-e263-4cfb-b811-79f337a3843c",
      "status": 0,
      "gen_cnt": 0,
      "mac_address": "",
      "vip_level": 0,
      "dispatch_time": "2025-05-16T14:29:27",
      "finish_time": null,
      "duration_seconds": 0,
      "time": "2025-05-16T14:29:27"
    }
  }
}

🧪 测试结果

1. 基本功能测试 ✅

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video_status \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json"
  }'

测试结果: ✅ 成功

2. 参数验证测试 ✅

空参数验证

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

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

3. URL格式处理测试 ✅

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video_status \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json"
  }'

结果: ✅ 成功

4. 不存在草稿测试 ✅

curl -X POST https://jy-api.fyshark.com/api/drafts/gen_video_status \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/nonexistent-draft.json"
  }'

结果: ✅ 成功

🏗️ 技术实现

文件结构 ✅

核心算法 ✅

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

验证机制 ✅

错误处理 ✅

📊 状态信息解析

返回字段说明

字段名 类型 说明
id number 任务唯一标识ID
user_id number 用户ID
draft_url string 草稿文件URL
video_url string 渲染完成的视频URL（空表示未完成）
zip_url string 打包文件URL（如有）
draft_id string 草稿唯一标识
status number 渲染状态码 (0=初始/排队, 1=进行中, 2=完成, -1=失败)
gen_cnt number 生成次数
dispatch_time string 任务提交时间
finish_time string/null 完成时间（null表示未完成）
duration_seconds number 视频时长（秒）

状态码含义

status 状态 说明
0 初始/排队 任务已提交，等待处理
1 渲染中 正在进行渲染处理
2 已完成 渲染成功完成，可获取视频
-1 渲染失败 渲染过程中出现错误

🔄 工作流程

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

🚀 使用示例

JavaScript 示例

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

// 使用示例
const draftUrl = "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json";
const statusInfo = await queryVideoStatus(draftUrl);

console.log('任务ID:', statusInfo.data.id);
console.log('渲染状态:', statusInfo.data.status);
if (statusInfo.data.video_url) {
  console.log('视频地址:', statusInfo.data.video_url);
}

Python 示例

import requests

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

# 使用示例
draft_url = "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json"
status_info = query_video_status(draft_url)

print(f"任务ID: {status_info['data']['id']}")
print(f"渲染状态: {status_info['data']['status']}")
if status_info['data']['video_url']:
    print(f"视频地址: {status_info['data']['video_url']}")

📖 应用场景

轮询监控 🔄

用户界面集成 📱

自动化流程 🤖

系统集成 🔗

⚠️ 注意事项

使用限制

  1. 查询频率: 建议查询间隔不少于5秒，避免过频查询
  2. 草稿文件: 必须是可访问的JSON格式文件
  3. 网络连接: 需要稳定的网络连接访问外部查询服务
  4. 数据时效性: 状态信息可能有1-2秒的缓存延迟

最佳实践

  1. 轮询策略: 采用指数退避算法避免频繁查询
  2. 错误重试: 网络错误时应进行适当重试
  3. 状态存储: 建议本地存储任务状态减少查询次数
  4. 用户体验: 为用户提供清晰的进度和状态反馈

🔗 相关接口

视频渲染系列

内容编辑系列

🚀 最佳实践

智能轮询

// ✅ 推荐：智能轮询策略
const waitForCompletion = async (draftUrl, options = {}) => {
  const { interval = 5000, timeout = 600000 } = options;
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeout) {
    try {
      const result = await queryVideoStatus(draftUrl);
      const status = result.data.status;
      
      // 检查完成状态
      if (status === 2) {
        return {
          success: true,
          video_url: result.data.video_url,
          duration: result.data.duration_seconds
        };
      }
      
      // 检查失败状态
      if (status === -1) {
        return {
          success: false,
          error: '渲染失败'
        };
      }
      
      // 等待下次查询
      await new Promise(resolve => setTimeout(resolve, interval));
      
    } catch (error) {
      console.warn('状态查询失败，重试中...', error.message);
      await new Promise(resolve => setTimeout(resolve, interval));
    }
  }
  
  throw new Error('等待渲染完成超时');
};

批量监控

// ✅ 推荐：批量状态监控
const monitorBatchStatus = async (draftUrls) => {
  const results = new Map();
  
  for (const draftUrl of draftUrls) {
    try {
      const status = await queryVideoStatus(draftUrl);
      results.set(draftUrl, status.data);
      
      console.log(`${draftUrl}: status=${status.data.status}`);
    } catch (error) {
      console.warn(`查询失败 ${draftUrl}:`, error.message);
      results.set(draftUrl, { error: error.message });
    }
  }
  
  return results;
};

✅ 开发总结

开发状态: 🎉 完全成功

完成情况

技术亮点

  1. 智能URL处理: 自动识别和处理剪映链接格式
  2. 完整参数验证: URL格式验证和完整的输入检查
  3. 可靠网络请求: 使用node-fetch确保HTTP请求稳定性
  4. 详细状态信息: 返回丰富的渲染任务状态数据
  5. 标准化响应: 统一的API响应格式和状态码

关键技术

实际测试数据

// 真实API响应示例
{
  "id": 316008,
  "status": 0,  // 0=排队中
  "draft_url": "https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/draft/0b3de2f7-e263-4cfb-b811-79f337a3843c.json",
  "video_url": "",  // 空表示未完成
  "dispatch_time": "2025-05-16T14:29:27",
  "finish_time": null  // null表示未完成
}

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

📚 文档中心 🏠 API首页
↑