主题切换
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_url | string | ✅ | - | 要保存的草稿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_url | string | 保存后的草稿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)
错误码说明
错误码 | 错误信息 | 说明 | 解决方案 |
---|---|---|---|
400 | draft_url是必填项 | 缺少草稿URL参数 | 提供有效的draft_url |
400 | draft_url格式无效 | URL格式不正确 | 检查URL格式是否正确 |
404 | 草稿不存在 | 指定的草稿无法找到 | 确认草稿URL是否正确且存在 |
500 | 保存失败 | 内部服务错误 | 联系技术支持或稍后重试 |
503 | 服务不可用 | 系统维护中 | 稍后重试 |
注意事项
- URL有效性: 确保传入的draft_url是有效且存在的
- 网络稳定性: 保存操作需要稳定的网络连接
- 频率控制: 避免过于频繁的保存操作
- 自动保存: 建议在长时间编辑时启用自动保存功能
- 错误处理: 保存失败时应该有重试机制
- 并发安全: 同一草稿的并发保存可能导致冲突
工作流程
- 验证draft_url参数
- 检查草稿是否存在
- 获取当前草稿状态
- 持久化保存草稿数据
- 返回保存结果
最佳实践
- 定期保存: 在重要操作后及时保存
- 自动保存: 为长时间编辑设置自动保存
- 错误恢复: 保存失败时提供重试机制
- 状态提示: 向用户显示保存状态
- 备份策略: 考虑多版本备份机制