文件问答 · 剧本解析

目录路径:文件问答 / 文件问答 · 剧本解析
文档 slug:file-qa-parse


剧本解析

POST /api/v1/apps/file_qa/parse

提交公网剧本、小说或故事大纲地址,接口返回平台 task_id,使用 GET /api/v1/tasks/{task_id} 查询结果。

参数

参数类型必填默认值说明
file_urlsstring[]是-1-8 个公网 HTTP/HTTPS 文档地址。
parse_modestring否autoauto、existing_episodes、screenplay_scenes、novel、outline、split_by_ai。
preserve_originalboolean否true固定为 true;传 false 会被拒绝,保证每集都有与行号对应的原文 content。
callback_urlstring否-任务完成或失败时接收 POST 通知的地址。
metadataobject否-业务关联字段。

解析模式

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(分集标题)替代。

全剧字段:

字段类型说明
titlestring短剧总标题。
type_judgementstring题材判断,例如“都市职场情感”。
core_themestring全剧核心主题。
story_outlinestring全剧完整故事梗概,含开端、发展、转折、高潮与结局。
series_bibleobject剧集设定集,包含 audience、core_hook、logline、series_arc、relationships、world_rules。
subjectsarray全局角色主体;每项使用稳定 source_id,含角色身份、背景、动机、人物弧光及关系。
locationsarray全局场景主体;每项使用稳定 source_id,含场景描述与叙事作用。
summarystring原始文档整体解析摘要;保留用于展示,不替代 story_outline。
charactersarray与 subjects 对应的兼容人物摘要,携带相同 source_id。
episodesarray分集数组,episode_count 必须严格等于其长度。

series_bible 字段:

字段类型说明
audiencestring目标受众画像。
core_hookstring核心爽点、悬念或情感钩子。
loglinestring一句话故事梗概。
series_arcstring全剧主线、阶段反转、高潮与结局。
relationshipsstring[]关键人物关系及其发展方向。
world_rulesstring[]世界观、时代、行业或规则一致性约束。

subjects[] 全局人物主体字段:

字段类型说明
source_idstring稳定上游角色标识,例如 character_001;只用于跨层关联,不是本地数据库 ID。
namestring人物名称。
categorystring固定为 character。
rolestring剧中身份,如女主角、反派、关键配角。
agestring年龄或年龄段描述。
descriptionstring人物外在特征与性格概述。
backgroundstring经历、家庭、职业等背景。
motivationstring当前核心诉求/目标。
arcstring全剧人物弧光或变化方向。
relationsarray关系数组;每项包含 target_source_id、target_name、relation。

locations[] 全局场景主体字段:

字段类型说明
source_idstring稳定上游场景标识,例如 location_001。
namestring场景名称。
descriptionstring场景视觉、空间与剧情信息。
narrative_rolestring场景的叙事作用,例如职场主场景、秘密揭露地点。

每集字段:

字段类型说明
episode_nointeger从 1 起严格连续递增;本地映射为 episode_number。
titlestring非空分集标题。
source_range.start_line / end_lineinteger原文包含式行范围。
contentstring按 source_range 从原文切出的内容,保留 L000001 等行号。
summarystring本集解析摘要。
story_outlinestring本集完整剧情:起因、过程、冲突、结果。
conflict_pointstring本集核心矛盾。
ending_hookstring结尾悬念或钩子。
charactersarray只引用 subjects 中已有 source_id;每项含 source_id、name、role、relation。
locationsarray只引用 locations 中已有 source_id;每项含 source_id、name。
continuityobjectopening_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。

同类文章