通过自定义插件接入扣子智能体

更新时间：2026-01-20

场景介绍

在秒哒中，许多基础创作需求已经可以通过内置的文本生成大模型插件来完成，例如生成故事内容、润色剧情片段或提供创意灵感等。这些通用能力能够覆盖大多数基础内容创作与表达需求的场景，帮助用户快速完成基础文本创作。

但当创作需求进一步升级，进入动画、视频或视觉叙事阶段时，单纯依赖通用模型往往难以完全满足实际使用需求。这是因为，此阶段中的分镜脚本并非普通的文本生成任务，它不仅要求模型理解剧情内容本身，还需要将文字信息系统性地拆解为有顺序、有节奏的镜头结构，并在每一个镜头中明确画面构图、人物状态以及对应的叙事功能。与此同时，分镜脚本的生成过程具有显著的方法论与规范属性。例如，不同类型或风格的视频在镜头划分方式、画面描述粒度以及整体分镜节奏上均存在明确差异，这要求模型能够遵循一套清晰、稳定且可复用的分镜写作规范。然而，仅依赖通用大模型进行生成时，模型往往难以在多次创作中稳定遵循这些规范，容易在不同输入条件下产生分镜结构不一致、镜头风格波动较大等问题，从而影响分镜脚本在实际制作流程中的可用性。

在这种情况下，一个围绕分镜生成流程定制的Coze智能体就显得尤为重要。通过Coze，你不仅可以在构建智能体时自主选择更适合创作需求的大模型，还可以为智能体配置专属知识库，用于系统性讲解分镜脚本的写作规范、拆解原则和输出格式，并将这些规范与“剧本解析、分镜拆解、镜头描述整理”等步骤整合进统一的行为逻辑中。例如，一个专门用于动画创作的分镜脚本生成Agent，能够在指定模型与分镜规范知识库的共同支持下，准确理解剧情结构，并按照统一标准将剧本内容自动拆解为清晰、有逻辑的分镜脚本。

当这个智能体在Coze中构建完成后，只需通过秒哒的自定义插件能力将其接入应用，即可在秒哒中直接调用这一专属创作能力。这样，秒哒不再只是提供通用的文本生成，而是能够在遵循既定分镜写作规范的前提下，高效完成从剧本到分镜脚本的转化过程，为后续视觉创作提供清晰、可执行的基础结构。

典型使用场景包括但不限于：

动画与视频创作场景，将文字剧本自动拆解为符合分镜规范的分镜脚本，明确镜头顺序、画面内容与叙事节奏。
分镜策划与脚本设计场景，基于统一写作规范生成分镜文本，用于前期创作讨论与方案确认。
漫画与视觉叙事创作场景，将剧情内容转化为规范化的镜头级描述，辅助画面设计与构图规划。

通过接入 Coze 智能体插件，秒哒应用不再局限于系统默认的通用能力，而是能够调用你定制的分镜脚本生成Agent，在需要理解剧情结构、遵循分镜写作规范并保持输出一致性的场景中，提供更加可控、高效的智能创作支持。

coze官方API文档入口：https://www.coze.cn/open/docs/developer_guides/coze_api_overview

搭建Agent流程

2.1 对话式智能体

进入coze开发平台，我们选择创建智能体的方式创建了一个分镜脚本生成器，用于帮助用户将文字剧本自动转换为分镜脚本。

步骤1: 登录coze AI智能体创建平台

输入账号密码完成登录

步骤2: 进入coze开发平台

在产品官方页面找到“扣子开发平台”
点击“快速开始”进入智能体创建区域

步骤3: 选择创建智能体

步骤4: 输入智能体名称以及功能介绍

步骤5: 创建成功

步骤6:创建知识库

创建好Agent后，通过创建知识库，可以让Agent生成更准确的回答。

2.2 测试Agent

成功创建分镜脚本Agent之后，可以先进行一次简单测试，用于确认分镜脚本生成Agent是否能够按预期完成分镜拆解。以下为推荐的操作步骤示例：

步骤1：进入coze项目开发页面，进入刚才创建的分镜脚本生成Agent：

步骤2：手动输入一段剧本，检查分镜脚本生成Agent生成的分镜结果是否可用：

2.3 查看并保存APIkey

在确认分镜脚本生成Agent能够正常工作后，下一步需要获取对应的 API Key，后续秒哒在调用 Coze 接口时将通过该 Key 进行鉴权。

进入扣子开发平台

在页面顶部空间列表中选择目标工作空间，在左侧导航栏选择API管理，进入API Key页面，创建API Key。

复制API Key，保存备用。
文档入口：https://www.coze.cn/open/docs/developer_guides/preparation

创建插件

3.1 对话生成插件

在秒哒官网对话生成自己的插件

阶段1：进入插件中心并创建插件

进入插件中心

登录秒哒平台。
在左侧导航栏找到 “插件”图标。
点击进入 插件中心，在插件中心右上角，点击 “创建插件”。

阶段2：提供API让秒哒自动配置

输入API信息生成插件

进入创建页面后，可根据示例中的模板格式输入API信息。

输入自己的插件配置信息（示例如下）

Plain Text

11.基础信息：
2插件名称：分镜脚本生成Agent
3插件描述：该插件适用于影视与视觉内容创作场景，通过调用你在coze中构建的分镜脚本 Agent，为用户提供具备连续对话能力的智能分镜生成服务。它能够基于剧本理解故事内容与创作意图，自动拆解剧情结构、镜头节奏与画面要素，并按照既定的创作风格与分镜规范输出专业分镜脚本，从而让秒哒在内容创作场景中实现更高质量、更贴近实际制作流程的视觉叙事支持。
4请求地址 (URL): https://api.coze.cn/v3/chat
5请求方式 (Method): POST
6鉴权方式: Header 中添加 Authorization: Bearer {Personal_Access_Token}
7* BOT_ID 也设置为预先配置参数，跟API_KEY一样
8
92. 请求参数说明 (Body)
10请在 JSON 请求体中包含以下参数：
11bot_id (String, 必选):指定要调用的 Bot ID。
12user_id (String, 必选):调用 API 的用户标识。
13stream (Boolean, 可选):是否开启流式响应。若要实现逐字输出，必须设置为 true。
14auto_save_history (Boolean, 可选):是否自动保存对话历史。默认为 true。
15additional_messages (Array, 可选):本次对话的消息列表。
16role: user
17content: 消息文本
18content_type: text
19conversation_id (String, 可选):对话 ID，用于标识一次多轮对话。
20首轮请求：可以不传此参数。服务端会自动生成一个新的对话 ID，并在响应数据中返回。
21后续请求：若希望保持上下文连续（即让 Bot 记得之前的聊天内容），必须携带上一轮响应中返回的 conversation_id。
22获取方式：请从响应结果（如 conversation.chat.created 或 conversation.message.delta 事件的数据包）中提取 conversation_id 字段。
23
243. 请求示例 (JSON)
25
26curl --location --request POST 'https://api.coze.cn/v3/chat?conversation_id=7374752000116113452' \
27--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
28--header 'Content-Type: application/json' \
29--data-raw '{
30    "bot_id": "734829333445931****",
31    "user_id": "123456789",
32    "stream": true,
33    "auto_save_history":true,
34    "additional_messages":[
35        {
36            "role":"user",
37            "content":"2024年10月1日是星期几",
38            "content_type":"text"
39        }
40    ]
41}'
42
434. 流式响应说明 (Response)
44响应采用 Server-Sent Events (SSE) 格式。需重点关注以下事件流以获取内容和 conversation_id：
45conversation.chat.created:对话创建成功。此处 data 中包含本次生成的 conversation_id。
46conversation.message.delta (核心内容):Bot 的流式回复内容。
47提取内容: 读取 data.content。
48提取ID: 读取 data.conversation_id (用于下一轮请求)。
49conversation.message.completed:当前消息生成结束。
50conversation.chat.completed:整个对话流程结束。
51
52响应数据包示例：
53
54event:conversation.chat.created
55// 在 chat 事件里，data 字段中的 id 为 Chat ID，即会话 ID。
56data:{"id":"7382159487131697202","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792949,"last_error":{"code":0,"msg":""},"status":"created","usage":{"token_count":0,"output_count":0,"input_count":0}}
57
58event:conversation.chat.in_progress
59data:{"id":"7382159487131697202","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792949,"last_error":{"code":0,"msg":""},"status":"in_progress","usage":{"token_count":0,"output_count":0,"input_count":0}}
60
61event:conversation.message.delta
62data:{"id":"7382159494123470858","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"2","content_type":"text","chat_id":"7382159487131697202"}
63
64event:conversation.message.delta
65data:{"id":"7382159494123470858","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"0","content_type":"text","chat_id":"7382159487131697202"}
66
67//省略模型回复的部分中间事件event:conversation.message.delta
68......
69
70event:conversation.message.delta
71data:{"id":"7382159494123470858","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"星期三","content_type":"text","chat_id":"7382159487131697202"}
72
73event:conversation.message.delta
74data:{"id":"7382159494123470858","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"。","content_type":"text","chat_id":"7382159487131697202"}
75
76event:conversation.message.completed
77data:{"id":"7382159494123470858","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"answer","content":"2024 年 10 月 1 日是星期三。","content_type":"text","chat_id":"7382159487131697202"}
78
79event:conversation.message.completed
80data:{"id":"7382159494123552778","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","role":"assistant","type":"verbose","content":"{\"msg_type\":\"generate_answer_finish\",\"data\":\"\",\"from_module\":null,\"from_unit\":null}","content_type":"text","chat_id":"7382159487131697202"}
81
82event:conversation.chat.completed
83data:{"id":"7382159487131697202","conversation_id":"7381473525342978089","bot_id":"7379462189365198898","completed_at":1718792949,"last_error":{"code":0,"msg":""},"status":"completed","usage":{"token_count":633,"output_count":19,"input_count":614}}
84
85event:done
86data:"[DONE]"
87
88
895. 常见错误排查
904000 Bad Request: 参数缺失或格式错误，请检查 bot_id 和 messages 结构。
914011 Unauthorized: Token 无效或过期，请重新生成 PAT。
9240002 Throttling: 调用频率过高，请稍后重试。