`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script-vertical` 本 API 用于提交一个异步的剧本还原（重绘场景）任务，通过分析多集短剧视频，输出可复用的角色、场景、预处理结果与逐集剧情分镜剧本，适用于短剧重绘、出海重制预处理、剧情解说等二次创作场景。 ## 使用方式本工具支持多种使用方式，以适应不同的业务场景，如首次分析、剧集增量更新、或利用外部资产进行还原。核心在于通过 `previous_manifest_url` 和 `current_asset_url` 两个参数来控制任务的分析流程和数据复用。 ### 场景一：首次分析 * 场景说明：当您需要从零开始分析一部短剧的前几集时。 * 使用说明：在 `videos` 数组中提供第一批视频的 URL 和对应的集数。任务将完整执行所有分析步骤，包括资产解析、预处理和剧本生成。 ### 场景二：接续分析（增量处理） * 场景说明：当您获得同一部短剧的后续剧集，希望在分析时复用已有资产（如角色、场景），以保证信息一致性时。 * 使用说明：在 `videos` 中传入新剧集的 URL，同时将上一次任务产出的 `manifest.json` URL 填入 `previous_manifest_url`。系统会自动加载前序结果，确保新旧剧集中的同一角色被正确识别，保证剧情分析的连续性。 ### 场景三：分步执行（先出资产，后出剧本） * **场景说明**：如果您希望在生成最终剧本前，先检查或手动修正资产分析（角色、场景等）的结果，或者希望分阶段控制成本，可以将整个任务拆分为“生成资产”和“生成剧本”两个步骤。 * **使用说明**： 1. 生成资产与预处理结果：提交一个任务，在 `videos` 中传入视频列表，并将 `return_type` 设置为 `["asset", "preprocess"]`。任务完成后，您将获得包含资产和预处理结果的 manifest.json 文件。 2. 使用已有资产生成剧本：确认第一步产物无误后，提交一个新的任务。请求中依然传入相同的 `videos` 列表，但同时将第一步产出的 `manifest.json` URL 填入 `current_asset_url` 参数，并将 `return_type` 设置为 `["script"]`。此任务将跳过资产分析，直接利用您提供的资产生成剧本，从而节约时间和成本。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`videos` |Array |是 |`[{"video_url": "...", "episode": 1}]` |待分析的短剧视频列表，每个列表项需同时指定视频 URL 及其在整部短剧中的实际集序号。详见下文 [Video 对象](https://docs.volcengine.com/docs/6448/2687170#43efdc7c)。 | |`drama_type` |String |否 |`Human` |短剧类型。支持取值：

* `AI`：（默认）AI 短剧（包括仿真人、2D/3D 动漫）。

* `Human`：真人短剧。 | |`return_type` |Array |否 |`["script", "preprocess"]` |需要返回的结果类型，可传入以下值的任意组合（至少 1 个）。不传时默认交付全部三类结果。

* `asset`：资产分析结果，包含角色、关系、场景等信息。

* `script`：逐集分镜剧本。

* `preprocess`：预处理结果（如基础分镜、人物锚点等）。 | |`previous_manifest_url` |String |否 |`https://.../prev_manifest.json` |用于接续分析的前序任务产物清单 manifest.json URL。传入后，系统会尝试复用前序任务中有效的分析结果，以保证资产（如角色）的一致性，并提高处理效率。 | |`current_asset_url` |String |否 |`https://.../asset_manifest.json` |当前待分析视频已有的资产清单 manifest.json URL。传入此参数将跳过资产分析环节，直接使用您提供的资产进入后续分析，可以显著降低任务耗时与成本。 | |`script_param` |Object |否 |`{"min_duration": 10, "max_duration": 30}` |剧情分镜时长配置。详见下文[Script param 对象](https://docs.volcengine.com/docs/6448/2687170#72b0fd94)。 | |`client_token` |String |否 |`your_unique_request_id_135` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_data` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://docs.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://docs.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://docs.volcengine.com/docs/6448/2519520)。 | #### Video 对象 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/drama_01.mp4` |待分析的视频 URL。

* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **格式限制**：支持 MP4、FLV、TS、AVI、MOV、WMV、MKV 等主流视频格式。暂不支持 HLS (M3U8) 格式的视频源。

* **数量限制**：单次任务支持传入 1 到 100 个视频文件。

* **视频时长限制**：单次任务处理的所有视频累计时长建议控制在 20 分钟以内。当前实测可处理最高约 60 分钟的视频，但随着时长的增加，任务耗时将会显著延长。

* **内容类型**：支持真人短剧、AI 仿真人、2D/3D 动漫。

* **分辨率限制**：同一任务内所有视频分辨率（宽高）必须一致，建议不超过 1080p。

* **字幕要求**：视频必须包含内嵌字幕（硬字幕）。 | |`episode` |Integer |是 |`1` |该视频在整部短剧中的实际集序号（从 1 开始或从 0 开始均可）。此序号用于关联产物，在跨任务接续分析时，请确保同一剧集的序号保持不变。 | #### Script param 对象 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`min_duration` |Number |否 |`10` |剧情分镜时长下限，单位：秒。取值范围 [1, 120]。默认值为 10。 | |`max_duration` |Number |否 |`30` |剧情分镜时长上限，单位：秒。取值范围 [5, 120]，且不得小于 `min_duration`。默认值为 30。为保证剧情完整性，不可再分的镜头或事件可能会超出此上限。 | ## 请求示例 ### 示例一：首次分析以下示例演示了如何对一部短剧的前两集首次提交剧本还原任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script-vertical' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "videos": [ { "video_url": "https://example.com/drama_episode_01.mp4", "episode": 1 }, { "video_url": "https://example.com/drama_episode_02.mp4", "episode": 2 } ], "drama_type": "Human", "return_type": ["asset", "script", "preprocess"] }' ``` ### 示例二：多任务接续分析以下示例演示了如何分两次任务，完整分析一部 4 集短剧，并通过 `previous_manifest_url` 参数确保两次任务的资产信息（如角色）保持一致。 #### 第 1 步：首次分析第 1\-2 集首先，提交一个任务来分析前两集。这是一个标准的首次分析任务，参考[示例一：首次分析](https://docs.volcengine.com/docs/6448/2687170#0b15ac86)。 #### 第 2 步：接续分析第 3\-4 集当您获得了新的第 3 和第 4 集时，为了保证与前两集的资产信息保持一致，您需要在新任务中引用上一次的产物。在本次请求中，`videos` 列表里只包含新剧集，同时使用 `previous_manifest_url` 参数传入第 1 步中获取的 `manifest.json` 链接。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script-vertical' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "videos": [ { "video_url": "https://example.com/drama_episode_03.mp4", "episode": 3 }, { "video_url": "https://example.com/drama_episode_04.mp4", "episode": 4 } ], "drama_type": "Human", "previous_manifest_url": "https://output.example.com/task1/manifest.json" }' ``` 通过这种方式，第二个任务在处理第 3、4 集时，会加载并复用第一个任务分析出的角色和场景信息，确保整个短剧（1\-4集）的资产和剧本具有良好的一致性。 ### 示例三：分步执行（先出资产，后出剧本）以下示例演示了如何将一次分析拆分为“生成资产”和“生成剧本”两步：先仅产出资产与预处理结果供检查或修正，确认无误后再复用该资产生成剧本，从而分阶段控制成本。 #### 第 1 步：生成资产与预处理结果首先，提交一个任务，传入待分析的视频列表，并将 `return_type` 设置为 `["asset", "preprocess"]`，使任务仅执行资产分析与预处理，暂不生成剧本。任务完成后，您将获得包含资产与预处理结果的 `manifest.json` 文件。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script-vertical' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "videos": [ { "video_url": "https://example.com/drama_episode_01.mp4", "episode": 1 }, { "video_url": "https://example.com/drama_episode_02.mp4", "episode": 2 } ], "drama_type": "Human", "return_type": ["asset", "preprocess"] }' ``` #### 第 2 步：使用已有资产生成剧本确认第 1 步产出的资产无误后，提交一个新任务。请求中依然传入相同的 `videos` 列表，同时将第 1 步产出的 `manifest.json` 链接填入 `current_asset_url`，并将 `return_type` 设置为 `["script"]`。此任务将跳过资产分析，直接复用您提供的资产生成剧本，从而节约时间和成本。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script-vertical' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "videos": [ { "video_url": "https://example.com/drama_episode_01.mp4", "episode": 1 }, { "video_url": "https://example.com/drama_episode_02.mp4", "episode": 2 } ], "drama_type": "Human", "current_asset_url": "https://output.example.com/task1/manifest.json", "return_type": ["script"] }' ``` 通过这种方式，您可以在生成最终剧本前先检查或手动修正资产结果，并按需分阶段控制任务成本。 ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |`success` |Boolean |任务是否成功提交。

* `true`：任务已成功提交到后台处理队列。

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 [Error 对象](https://docs.volcengine.com/docs/6448/2687170#2d9b88a4)。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-drama-script-vertical-123456789", "request_id": "20240521150000ABCDEFG12345" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20240521150500XYZW12345", "error": { "code": "InvalidParameter", "message": "The number of items in 'videos' must be between 1 and 100.", "param": "videos", "type": "BadRequest" } } ``` ## 异步任务结果剧本还原（重绘场景）是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果： * **方法一（轮询查询）：** 使用提交任务时获取的 `task_id`，定期调用[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到 `status` 字段变为 `completed` 或 `failed`。 * **方法二（事件回调）：** 在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 `callback_url` 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅[事件回调](https://docs.volcengine.com/docs/6448/2288701)。当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。 |参数 |类型 |示例 |描述 | |---|---|---|---| |`result_url` |String |`https://.../manifest.json?auth_key=...` |结果清单 manifest.json 的下载 URL。通过该清单可索引本次任务交付的所有产物文件。 | |`input_duration` |Number |`245.5` |输入视频的原始总时长，单位为秒。 | |`duration` |Number |`245.5` |用于计量计费的时长，单位为秒。 | 以下是一个任务执行完成后的完整任务信息示例： ```JSON { "task_info": { "task_id": "amk-tool-drama-script-vertical-123456789", "request_id": "20240521150000ABCDEFG12345", "status": "completed", "result": { "result_url": "https://example.volcvideo.com/manifest.json?auth_key=...", "input_duration": 245.5, "duration": 245.5 }, "created_at": 1777291767, "finished_at": 1777291851, "expires_at": 1777464650 } } ```