CREATE_DRAFT API 接口文档

📄 API_DRAFT.md 🕒 8/10/2025, 6:55:14 PM 📏 6KB

CREATE_DRAFT API 接口文档

接口信息

POST /api/drafts/create_draft

功能描述

创建新的视频草稿，设置画布尺寸和基本配置。该接口会生成一个空白的视频项目草稿，提供后续素材添加和编辑操作的基础。支持自定义画布尺寸，默认为竖屏比例（1080x1920）。

请求参数

{
  "width": 1080,
  "height": 1920,
  "user_id": 12345
}

参数说明

参数名 类型 必填 默认值 说明
width number ❌ 1080 草稿画布宽度（像素）
height number ❌ 1920 草稿画布高度（像素）
user_id number ❌ - 用户ID，提供后会保存草稿记录

常用画布尺寸

类型 尺寸 说明
竖屏视频 1080x1920 抖音、快手等短视频平台
横屏视频 1920x1080 YouTube、B站等长视频平台
方形视频 1080x1080 Instagram等社交平台
超宽屏 2560x1080 电影感视频

响应格式

成功响应 (200)

{
  "status": "success",
  "message": "草稿创建成功",
  "data": {
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-08-01/draft/xxx.json",
    "tip_url": "快速入门必看指南，请访问：https://www.51aigc.cc/#/cozeTutorial/detail/13",
    "record_saved": false
  }
}

错误响应 (4xx/5xx)

{
  "status": "error",
  "message": "错误信息",
  "error": "详细错误描述"
}

使用示例

cURL 示例

# 基本创建（使用默认尺寸）
curl -X POST https://jy-api.fyshark.com/api/drafts/create_draft \
  -H "Content-Type: application/json" \
  -d '{}'

# 自定义尺寸创建
curl -X POST https://jy-api.fyshark.com/api/drafts/create_draft \
  -H "Content-Type: application/json" \
  -d '{
    "width": 1920,
    "height": 1080,
    "user_id": 12345
  }'

JavaScript 示例

const createDraft = async (width = 1080, height = 1920, userId = null) => {
  const response = await fetch('https://jy-api.fyshark.com/api/drafts/create_draft', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      width,
      height,
      user_id: userId
    })
  });

  const result = await response.json();
  return result;
};

// 使用示例
try {
  // 创建默认尺寸草稿
  const draft1 = await createDraft();
  console.log('草稿创建成功:', draft1.data.draft_url);

  // 创建横屏草稿
  const draft2 = await createDraft(1920, 1080, 12345);
  console.log('横屏草稿创建成功:', draft2.data.draft_url);
} catch (error) {
  console.error('创建失败:', error);
}

Python 示例 (可选)

import requests
import json

def create_draft(width=1080, height=1920, user_id=None):
    data = {"width": width, "height": height}
    if user_id:
        data["user_id"] = user_id
    
    response = requests.post(
        'https://jy-api.fyshark.com/api/drafts/create_draft',
        headers={'Content-Type': 'application/json'},
        json=data
    )
    return response.json()

# 使用示例
result = create_draft(1920, 1080, 12345)
print(f"草稿URL: {result['data']['draft_url']}")

错误码说明

错误码 错误信息 说明 解决方案
400 参数格式错误 width或height不是有效数字 检查参数类型是否正确
400 尺寸参数无效 width或height小于等于0 使用正数作为画布尺寸
500 草稿创建失败 内部处理错误 检查服务器状态，重试请求
500 OSS上传失败 云存储服务异常 检查网络连接，稍后重试
500 用户记录保存失败 用户ID无效或数据库异常 检查user_id参数有效性

注意事项

  1. 默认参数: 如果不提供width和height，系统会使用默认的1080x1920尺寸
  2. 用户记录: 只有提供有效user_id时才会保存草稿记录
  3. URL格式: 返回的draft_url需要在后续操作中使用，请妥善保存
  4. 画布尺寸: 建议使用常见的视频尺寸比例，避免奇怪的尺寸导致播放问题
  5. 存储位置: 草稿文件存储在阿里云OSS上，URL有效期很长但不是永久的

工作流程

  1. 接收并验证请求参数（width, height, user_id）
  2. 使用jy_draft库创建新的Draft对象
  3. 设置画布尺寸和基础配置
  4. 使用AES-256-CBC加密草稿内容
  5. 生成唯一文件名并上传到阿里云OSS
  6. 如果提供user_id，保存草稿记录到数据库
  7. 返回草稿URL和相关信息

技术细节

加密机制

存储结构

OSS路径格式: /{YYYY-MM-DD}/draft/{UUID}.json
示例: /2025-08-01/draft/a1b2c3d4-e5f6-7890-abcd-ef1234567890.json

草稿结构

{
  "canvas_config": {
    "width": 1080,
    "height": 1920
  },
  "duration": 10000000,
  "tracks": [],
  "materials": {}
}

最佳实践

画布尺寸选择

// 根据平台选择合适的尺寸
const platformSizes = {
  tiktok: { width: 1080, height: 1920 },    // 抖音
  youtube: { width: 1920, height: 1080 },   // YouTube
  instagram: { width: 1080, height: 1080 }, // Instagram
  wechat: { width: 1080, height: 1920 }     // 微信视频号
};

const createPlatformDraft = async (platform, userId) => {
  const size = platformSizes[platform];
  return await createDraft(size.width, size.height, userId);
};

错误处理

const createDraftWithRetry = async (width, height, userId, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const result = await createDraft(width, height, userId);
      if (result.status === 'success') {
        return result;
      }
    } catch (error) {
      console.warn(`创建草稿失败，第${i + 1}次尝试:`, error.message);
      if (i === maxRetries - 1) throw error;
      
      // 等待后重试
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
};

URL管理

class DraftManager {
  constructor() {
    this.drafts = new Map();
  }

  async createAndStore(width, height, userId, name) {
    const result = await createDraft(width, height, userId);
    if (result.status === 'success') {
      this.drafts.set(name, {
        url: result.data.draft_url,
        created: new Date(),
        width,
        height,
        userId
      });
    }
    return result;
  }

  getDraft(name) {
    return this.drafts.get(name);
  }

  listDrafts() {
    return Array.from(this.drafts.entries());
  }
}

相关接口

更新日志

📖 文档版本: v1.3.0
🔄 最后更新: 2025-08-01
👤 维护者: Developer

📚 文档中心 🏠 API首页
↑