编辑文档 - 口播文案模块 API 接口文档

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

# 口播文案模块 API 接口文档

> Base URL: `https://doc.softlv.top`
> 所有接口均返回 JSON，`Content-Type: application/json`

---

## 数据模型

### video_scripts 表字段

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键，自增 |
| title | text | 文档标题 |
| content | text | **纯文本正文**（不含 frontmatter） |
| summary | text | 摘要，如"86秒口播文案，441字，1.4倍速" |
| tags | text | 标签，逗号分隔，如"口播文案,agency-agents,AI-Agent" |
| category | varchar(255) | 分类，默认"口播文案" |
| preloaded_comments | text | 预载评论，多条用 `||` 分隔，格式 `用户名:内容` |
| short_title | varchar(64) | 视频号短标题（≤16字） |
| video_duration | int | 视频时长（秒） |
| speech_rate | decimal(3,2) | 语速倍数，默认 1.00 |
| video_description | text | 视频号描述文案 |
| hashtags | text | 话题标签，JSON 数组格式 |
| featured_comment | text | 精选评论 |
| content_hash | varchar(64) | 内容哈希（去重用） |
| feishu_doc_id | text | 飞书文档 ID |
| feishu_url | text | 飞书文档链接 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

---

## 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/video-scripts` | 获取口播文案列表 |
| POST | `/api/video-scripts` | 创建口播文案 |
| GET | `/api/video-scripts/<id>` | 获取单个口播文案详情 |
| PUT | `/api/video-scripts/<id>` | 更新口播文案 |
| DELETE | `/api/video-scripts/<id>` | 删除口播文案 |

---

## 1. 获取口播文案列表

GET /api/video-scripts

Query 参数：
- search: 搜索关键词，匹配 title / content / short_title
- category: 按分类筛选

响应示例：
[id=1 的口播文案列表数据]

---

## 2. 创建口播文案

POST /api/video-scripts
Content-Type: application/json

必填字段：title, content
可选字段：summary, tags, category, preloaded_comments, short_title, video_duration, speech_rate, video_description, hashtags, featured_comment

---

## 3. 获取单个口播文案详情

GET /api/video-scripts/<id>

返回完整字段，content 为纯文本不含 frontmatter，hashtags 始终返回数组。

---

## 4. 更新口播文案

PUT /api/video-scripts/<id>

任意字段均可更新。tags 数组自动转逗号分隔，hashtags 数组自动转 JSON。

---

## 5. 删除口播文案

DELETE /api/video-scripts/<id>

返回 {"message": "删除成功"}

---

## Python 调用示例

import requests

payload = {
    "title": "agency-agents 口播文案",
    "content": "147个AI Agent正文内容...",
    "summary": "86秒口播文案，441字，1.4倍速",
    "category": "口播文案",
    "tags": "口播文案,agency-agents,AI-Agent",
    "short_title": "装了147个Agent，我后悔了",
    "video_duration": 86,
    "speech_rate": 1.4,
    "video_description": "213天涨到10万Star的agency-agents...",
    "hashtags": ["#AIAgent", "#agencyagents", "#AI团队", "#多Agent协作", "#Hermes", "#ClaudeCode", "#AIGC", "#AI工具", "#AI编程", "#技能提升"],
    "featured_comment": "终于有人说实话了！...",
    "preloaded_comments": "终于有人说实话了！..."
}

resp = requests.post("https://doc.softlv.top/api/video-scripts", headers={"Content-Type": "application/json"}, json=payload, timeout=20)
print(resp.json())

resp = requests.get("https://doc.softlv.top/api/video-scripts/1")
print(resp.json())

resp = requests.put("https://doc.softlv.top/api/video-scripts/1", json={"short_title": "装了147个Agent，我后悔了", "speech_rate": 1.5}, timeout=20)
print(resp.json())

resp = requests.delete("https://doc.softlv.top/api/video-scripts/1")
print(resp.json())

---

## 存储方案总结

| 信息类型 | 存储位置 | 说明 |
|----------|----------|------|
| 基础信息（标题/分类/正文） | 接口原生字段 | 数据库独立列 |
| 视频元信息（时长/语速/短标题） | 数据库独立列 | content 直接存纯文本 |
| 话题标签/视频描述/精选评论 | 数据库独立列 | hashtags 存为 JSON 字符串 |
| 预载评论 | preloaded_comments 字段 | || 分隔，格式 用户名:内容 |

摘要

标签多个标签用逗号分隔

分类