Skip to content
当前页导航

SAVE_DRAFT API 接口文档

接口信息

POST /v1/save_draft

功能描述

保存剪映草稿。该接口用于保存当前的草稿状态,确保编辑的内容得到持久化存储。通常在完成一系列编辑操作后调用此接口,以防止编辑内容丢失。

请求参数

json
{
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-05-28/draft/2f52a63b-8c6a-4417-8b01-1b2a569ccb6c.json"
}

参数说明

参数名类型必填默认值说明
draft_urlstring-要保存的草稿URL

参数详解

draft_url

  • 类型: 字符串
  • 必填: 是
  • 格式: 完整的草稿URL,通常由create_draft接口返回
  • 示例: https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/...

URL格式说明

草稿URL通常包含以下部分:

  • 域名: https://ts.fyshark.com
  • 路径: /#/cozeToJianyin
  • 参数: drafId指向实际的草稿JSON文件URL

响应格式

成功响应 (200)

json
{
  "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-05-28/draft/2f52a63b-8c6a-4417-8b01-1b2a569ccb6c.json"
}

响应字段说明

字段名类型说明
draft_urlstring保存后的草稿URL,通常与请求中的URL相同

错误响应 (4xx/5xx)

json
{
  "detail": "错误信息描述"
}

使用示例

cURL 示例

1. 基本保存草稿

bash
curl -X POST https://api.example.com/v1/save_draft \
  -H "Content-Type: application/json" \
  -d '{
    "draft_url": "https://ts.fyshark.com/#/cozeToJianyin?drafId=https://video-snot-12220.oss-cn-shanghai.aliyuncs.com/2025-05-28/draft/example.json"
  }'

JavaScript 示例

javascript
const saveDraft = async (draftUrl) => {
  const response = await fetch('/v1/save_draft', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ draft_url: draftUrl })
  });
  return response.json();
};

// 保存草稿
const draftUrl = "https://ts.fyshark.com/#/cozeToJianyin?drafId=...";
const result = await saveDraft(draftUrl);
console.log('草稿保存成功:', result.draft_url);

高级JavaScript示例

javascript
class DraftManager {
  constructor(baseUrl = 'https://api.example.com') {
    this.baseUrl = baseUrl;
  }

  async saveDraft(draftUrl) {
    const response = await fetch(`${this.baseUrl}/v1/save_draft`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ draft_url: draftUrl })
    });
    
    if (!response.ok) {
      throw new Error(`保存草稿失败: ${response.statusText}`);
    }
    
    return response.json();
  }

  // 自动保存功能
  async autoSave(draftUrl, intervalMs = 30000) {
    const saveInterval = setInterval(async () => {
      try {
        await this.saveDraft(draftUrl);
        console.log(`自动保存成功: ${new Date().toLocaleTimeString()}`);
      } catch (error) {
        console.error('自动保存失败:', error);
      }
    }, intervalMs);

    // 返回停止自动保存的函数
    return () => clearInterval(saveInterval);
  }

  // 编辑流程中的保存
  async editWorkflow(draftUrl, operations) {
    const results = [];
    
    for (const operation of operations) {
      try {
        // 执行编辑操作(这里是示例)
        const editResult = await operation();
        results.push(editResult);
        
        // 每次操作后自动保存
        await this.saveDraft(draftUrl);
        console.log(`操作完成并保存: ${operation.name}`);
        
      } catch (error) {
        console.error(`操作失败: ${operation.name}`, error);
        results.push({ error: error.message });
      }
    }
    
    return results;
  }

  // 批量保存多个草稿
  async saveMutipleDrafts(draftUrls) {
    const results = {};
    
    for (const [name, url] of Object.entries(draftUrls)) {
      try {
        const result = await this.saveDraft(url);
        results[name] = result;
        
        // 添加延迟避免请求过快
        await new Promise(resolve => setTimeout(resolve, 100));
      } catch (error) {
        console.error(`保存草稿失败 ${name}:`, error);
        results[name] = { error: error.message };
      }
    }
    
    return results;
  }
}

// 使用示例
const draftManager = new DraftManager();

// 基本保存
const draftUrl = "https://ts.fyshark.com/#/cozeToJianyin?drafId=...";
await draftManager.saveDraft(draftUrl);

// 启动自动保存(每30秒保存一次)
const stopAutoSave = await draftManager.autoSave(draftUrl, 30000);

// 编辑完成后停止自动保存
setTimeout(() => {
  stopAutoSave();
  console.log('自动保存已停止');
}, 300000); // 5分钟后停止

// 批量保存多个草稿
const multipleDrafts = {
  "project1": "https://ts.fyshark.com/#/cozeToJianyin?drafId=project1.json",
  "project2": "https://ts.fyshark.com/#/cozeToJianyin?drafId=project2.json"
};
const saveResults = await draftManager.saveMutipleDrafts(multipleDrafts);

Python 示例

python
import requests
import time
import threading
from typing import Dict, List, Callable

class DraftSaver:
    def __init__(self, base_url: str = "https://api.example.com"):
        self.base_url = base_url
        self._auto_save_threads = {}

    def save_draft(self, draft_url: str) -> Dict:
        """保存草稿"""
        response = requests.post(
            f'{self.base_url}/v1/save_draft',
            headers={'Content-Type': 'application/json'},
            json={"draft_url": draft_url}
        )
        response.raise_for_status()
        return response.json()

    def auto_save(self, draft_url: str, interval_seconds: int = 30) -> str:
        """启动自动保存,返回线程ID用于停止"""
        def save_loop():
            while True:
                try:
                    self.save_draft(draft_url)
                    print(f"自动保存成功: {time.strftime('%H:%M:%S')}")
                    time.sleep(interval_seconds)
                except Exception as e:
                    print(f"自动保存失败: {e}")
                    time.sleep(5)  # 出错后等待5秒再重试

        thread_id = f"auto_save_{int(time.time())}"
        thread = threading.Thread(target=save_loop, daemon=True)
        thread.start()
        self._auto_save_threads[thread_id] = thread
        
        return thread_id

    def stop_auto_save(self, thread_id: str):
        """停止自动保存"""
        if thread_id in self._auto_save_threads:
            # 线程设为daemon,程序结束时会自动停止
            del self._auto_save_threads[thread_id]
            print(f"自动保存线程 {thread_id} 已标记停止")

    def save_with_retry(self, draft_url: str, max_retries: int = 3) -> Dict:
        """带重试机制的保存"""
        for attempt in range(max_retries):
            try:
                return self.save_draft(draft_url)
            except Exception as e:
                if attempt == max_retries - 1:
                    raise e
                print(f"保存失败,第{attempt + 1}次重试: {e}")
                time.sleep(2 ** attempt)  # 指数退避

# 使用示例
saver = DraftSaver()

# 基本保存
draft_url = "https://ts.fyshark.com/#/cozeToJianyin?drafId=example.json"
result = saver.save_draft(draft_url)
print(f"草稿保存成功: {result['draft_url']}")

# 带重试的保存
try:
    result = saver.save_with_retry(draft_url, max_retries=3)
    print("保存成功(带重试机制)")
except Exception as e:
    print(f"保存最终失败: {e}")

# 启动自动保存
auto_save_id = saver.auto_save(draft_url, interval_seconds=30)
print(f"自动保存已启动,ID: {auto_save_id}")

# 10分钟后停止自动保存
time.sleep(600)
saver.stop_auto_save(auto_save_id)

错误码说明

错误码错误信息说明解决方案
400draft_url是必填项缺少草稿URL参数提供有效的draft_url
400draft_url格式无效URL格式不正确检查URL格式是否正确
404草稿不存在指定的草稿无法找到确认草稿URL是否正确且存在
500保存失败内部服务错误联系技术支持或稍后重试
503服务不可用系统维护中稍后重试

注意事项

  1. URL有效性: 确保传入的draft_url是有效且存在的
  2. 网络稳定性: 保存操作需要稳定的网络连接
  3. 频率控制: 避免过于频繁的保存操作
  4. 自动保存: 建议在长时间编辑时启用自动保存功能
  5. 错误处理: 保存失败时应该有重试机制
  6. 并发安全: 同一草稿的并发保存可能导致冲突

工作流程

  1. 验证draft_url参数
  2. 检查草稿是否存在
  3. 获取当前草稿状态
  4. 持久化保存草稿数据
  5. 返回保存结果

最佳实践

  1. 定期保存: 在重要操作后及时保存
  2. 自动保存: 为长时间编辑设置自动保存
  3. 错误恢复: 保存失败时提供重试机制
  4. 状态提示: 向用户显示保存状态
  5. 备份策略: 考虑多版本备份机制

相关接口