文件问答 · 剧本解析
目录路径:文件问答 / 文件问答 · 剧本解析
文档 slug:file-qa-parse
剧本解析
POST /api/v1/apps/file_qa/parse
提交公网剧本、小说或故事大纲地址,接口返回平台 task_id,使用 GET /api/v1/tasks/{task_id} 查询结果。
参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
file_urls | string[] | 是 | - | 1-8 个公网 HTTP/HTTPS 文档地址。 |
parse_mode | string | 否 | auto | auto、existing_episodes、screenplay_scenes、novel、outline、split_by_ai。 |
preserve_original | boolean | 否 | true | 固定为 true;传 false 会被拒绝,保证每集都有与行号对应的原文 content。 |
callback_url | string | 否 | - | 任务完成或失败时接收 POST 通知的地址。 |
metadata | object | 否 | - | 业务关联字段。 |
解析模式
parse_mode 值 | 适用输入 | 切分与输出规则 | 使用建议 |
|---|---|---|---|
auto | 文档类型不确定,或混合了标题、场次、章节与大纲。 | 平台依次尝试识别已有集标题、场次剧本、小说章节,最后按大纲结构判断;实际识别类型在结果 detected_type 返回。 | 默认选项。已有明确格式时,建议改用对应固定模式,减少识别歧义。 |
existing_episodes | 原文已经有“第一集”“第 1 集”“EP01”等明确分集标题。 | 以已有分集标题和原文边界切分,不重新规划集数或改写剧情。 | 已完成分集的剧本、分集大纲、分集小说。 |
screenplay_scenes | 有场景标记、时间、人物、动作和对白,但没有正式分集标题。 | 以场次、冲突推进和转场聚合为剧集;生成连续集号、集标题、单集大纲、冲突与结尾钩子。 | 标准影视剧本、场景稿、对白稿。 |
novel | 小说、连载正文、章节体故事。 | 以章节、段落、人物目标和剧情节点切分;避免把单纯字数作为切分依据。 | 网文、小说原稿、故事正文。 |
outline | 人物小传、故事梗概、分场大纲、策划案,正文对白较少。 | 以剧情阶段、事件因果、人物目标和冲突节点规划为多集大纲。 | 尚未写成完整剧本的项目。 |
split_by_ai | 没有可靠标题、场次或章节边界,且允许 AI 基于剧情结构判定集与集边界。 | AI 根据起因、升级、反转、高潮和悬念决定边界;仍必须返回可追溯的原文行范围,不能凭空补写原文。 | 非标准格式、素材拼接稿;建议人工确认结果后再进入剧集生产。 |
平台不提供目标集数或单集时长参数,不为了凑数量改写原始剧情。parse_mode 只控制识别/切分策略,不改变 content 的原文来源。
请求示例
{
"file_urls": ["https://example.com/script.docx"],
"parse_mode": "auto",
"preserve_original": true
}
结果结构
完成后 data.result 返回可直接映射为“多集大纲 → 剧集生产”的完整契约。缺少必填字段、占位文本、错误人物/场景引用或不连续的集号都会作为 result_contract_invalid 失败,不返回半成品。
data.result.title 是整部短剧总标题且必须非空;不得省略,也不能以 episodes[].title(分集标题)替代。
全剧字段:
| 字段 | 类型 | 说明 |
|---|---|---|
title | string | 短剧总标题。 |
type_judgement | string | 题材判断,例如“都市职场情感”。 |
core_theme | string | 全剧核心主题。 |
story_outline | string | 全剧完整故事梗概,含开端、发展、转折、高潮与结局。 |
series_bible | object | 剧集设定集,包含 audience、core_hook、logline、series_arc、relationships、world_rules。 |
subjects | array | 全局角色主体;每项使用稳定 source_id,含角色身份、背景、动机、人物弧光及关系。 |
locations | array | 全局场景主体;每项使用稳定 source_id,含场景描述与叙事作用。 |
summary | string | 原始文档整体解析摘要;保留用于展示,不替代 story_outline。 |
characters | array | 与 subjects 对应的兼容人物摘要,携带相同 source_id。 |
episodes | array | 分集数组,episode_count 必须严格等于其长度。 |
series_bible 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
audience | string | 目标受众画像。 |
core_hook | string | 核心爽点、悬念或情感钩子。 |
logline | string | 一句话故事梗概。 |
series_arc | string | 全剧主线、阶段反转、高潮与结局。 |
relationships | string[] | 关键人物关系及其发展方向。 |
world_rules | string[] | 世界观、时代、行业或规则一致性约束。 |
subjects[] 全局人物主体字段:
| 字段 | 类型 | 说明 |
|---|---|---|
source_id | string | 稳定上游角色标识,例如 character_001;只用于跨层关联,不是本地数据库 ID。 |
name | string | 人物名称。 |
category | string | 固定为 character。 |
role | string | 剧中身份,如女主角、反派、关键配角。 |
age | string | 年龄或年龄段描述。 |
description | string | 人物外在特征与性格概述。 |
background | string | 经历、家庭、职业等背景。 |
motivation | string | 当前核心诉求/目标。 |
arc | string | 全剧人物弧光或变化方向。 |
relations | array | 关系数组;每项包含 target_source_id、target_name、relation。 |
locations[] 全局场景主体字段:
| 字段 | 类型 | 说明 |
|---|---|---|
source_id | string | 稳定上游场景标识,例如 location_001。 |
name | string | 场景名称。 |
description | string | 场景视觉、空间与剧情信息。 |
narrative_role | string | 场景的叙事作用,例如职场主场景、秘密揭露地点。 |
每集字段:
| 字段 | 类型 | 说明 |
|---|---|---|
episode_no | integer | 从 1 起严格连续递增;本地映射为 episode_number。 |
title | string | 非空分集标题。 |
source_range.start_line / end_line | integer | 原文包含式行范围。 |
content | string | 按 source_range 从原文切出的内容,保留 L000001 等行号。 |
summary | string | 本集解析摘要。 |
story_outline | string | 本集完整剧情:起因、过程、冲突、结果。 |
conflict_point | string | 本集核心矛盾。 |
ending_hook | string | 结尾悬念或钩子。 |
characters | array | 只引用 subjects 中已有 source_id;每项含 source_id、name、role、relation。 |
locations | array | 只引用 locations 中已有 source_id;每项含 source_id、name。 |
continuity | object | opening_state 与 closing_state,描述本集首尾状态衔接。 |
continuity.opening_state 说明开场时人物关系、目标或事件状态;continuity.closing_state 说明结尾后发生的变化,供下一集承接。ending_hook 是对观众的下一集悬念,二者不能互相替代。
人物和场景的 source_id 是上游稳定关联键,平台不接受本地主体库 ID;同名但不同 source_id 不会被自动合并。
完整 data.result 示例
{
"detected_type": "screenplay_scenes",
"parse_mode": "auto",
"episode_count": 1,
"title": "逆风翻盘",
"type_judgement": "都市职场情感",
"core_theme": "主角在职场压力中重建自我价值",
"story_outline": "林晓从入职受挫到完成项目反转,并建立新的职业选择。",
"series_bible": {
"audience": "都市年轻女性",
"core_hook": "职场逆袭与情感博弈",
"logline": "新人在压力中完成逆风翻盘。",
"series_arc": "受挫、反击、反转、胜利。",
"relationships": ["林晓与陈总:上下级关系,逐渐形成信任与对抗"],
"world_rules": ["故事发生在当代互联网公司,晋升规则前后一致"]
},
"subjects": [{
"source_id": "character_001", "name": "林晓", "category": "character", "role": "女主角", "age": "25岁",
"description": "外柔内刚的职场新人", "background": "来自小城,初入互联网行业", "motivation": "证明自身能力并获得独立", "arc": "从回避冲突成长为主动承担责任", "relations": []
}],
"locations": [{"source_id": "location_001", "name": "公司办公区", "description": "开放式办公区", "narrative_role": "职场主场景"}],
"episodes": [{
"episode_no": 1, "title": "第一集 初入职场", "source_range": {"start_line": 1, "end_line": 86}, "content": "L000001 ……",
"summary": "林晓第一天入职受挫。", "story_outline": "林晓汇报失误,与陈总冲突后决定重做方案。", "conflict_point": "汇报失误引发正面冲突", "ending_hook": "陈总要求她当晚重做方案",
"characters": [{"source_id": "character_001", "name": "林晓", "role": "主角", "relation": "本人"}], "locations": [{"source_id": "location_001", "name": "公司办公区"}],
"continuity": {"opening_state": "林晓第一天入职,尚未获得认可", "closing_state": "林晓决定留下证明自己"}
}],
"summary": "原始文档整体解析摘要",
"characters": [{"source_id": "character_001", "name": "林晓", "role": "女主角"}],
"usage": {"input_tokens": 12000, "output_tokens": 1800, "total_tokens": 13800}
}
10 万字以上文档在后台按段落/场次分块处理,再合并边界和剧集编号。
异步获取结果
剧本解析接口本身是异步 API,提交后立即返回 task_id,stream 不会建立 SSE 连接。请轮询任务接口:
GET /api/v1/tasks/{task_id}
Authorization: Bearer <YOUR_API_KEY>
任务响应状态为 pending 或 processing 时继续轮询;状态为 completed 时,从 result.episodes、result.summary、result.characters 读取结果;状态为 failed 时读取 error.code 和 error.message。也可以传 callback_url 接收完成/失败通知,但最终结果仍以任务查询接口为准。
{
"code": 1,
"data": {
"task_id": "202609180002",
"status": "completed",
"result": {"episode_count": 3, "episodes": []},
"usage": {"input_tokens": 12000, "output_tokens": 1800, "points_cost": 54.6}
}
}
计费
输入 2,600 点/百万 Token,输出 13,000 点/百万 Token。所有分块的 usage 汇总后结算:
总点数 = input_tokens × 2600 / 1000000 + output_tokens × 13000 / 1000000
价格查询:GET /api/v1/pricing?type=app_api&app_code=file_qa&api_code=parse。