`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/video-ocr` 本 API 用于提交一个异步的视频字幕识别（OCR）任务，能够识别输入的视频画面中的字幕信息，输出为一份带时间戳的结构化文本数据。

说明

如需了解完整的使用流程和应用示例，请参阅视频识别字幕（OCR）。

## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/media.mp4` |待识别的视频 URL。

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

* **支持格式**：`mp4`, `flv`, `ts`, `avi`, `mov`, `wmv`, `mkv` 等主流视频格式。

* **视频时长**：单文件时长不得超过 10 分钟。

* **输入视频分辨率**：支持 240p～4k。 | |`mode` |String |否 |`Subtitle` |工作模式，默认为 `Subtitle`。

* `Subtitle`：字幕识别模式。仅识别视频画面中符合字幕特征的文本。适用于快速提取视频对白、生成字幕稿等场景。

* `Detailed`：详细识别模式。识别画面中更详细的文本信息。包括字幕、水印、台标、标题等。该模式的返回结果会额外包含以下字段，方便进行深入分析：

* `text_label`: 将文本分类为 `Subtitle`（字幕）或`Others`（其他文字）。

* `text_location`: 提供文本在画面中的精确坐标。 | |`client_token` |String |否 |`your_unique_request_id_134` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](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。详情请参考[按项目或 API Key 分账](https://docs.volcengine.com/docs/6448/2519520)。 | ## 请求示例以下示例演示了如何识别一个视频中的字幕内容。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/video-ocr' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_movie_clip.mp4", "mode": "Subtitle" }' ``` ## 响应说明 ### 任务提交成功响应任务提交成功后，接口会立即返回以下 JSON 对象。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

* `true`：成功。

* `false`：失败。更多信息请查看[错误处理](https://docs.volcengine.com/docs/6448/2386123#AizB0LogJJ)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务进度和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-video-ocr-123456789", "request_id": "20240521120000ABCDEFG12345" } ``` ## 异步任务结果任务处理完成后，通过[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) 或[事件回调](https://docs.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`subtitles` |Array |字幕片段列表。每个元素是一个包含字幕文本和时间戳的对象，详见下文[Subtitle 对象](https://docs.volcengine.com/docs/6448/2386123#e0a7d42b)。 | |`duration` |Number |输入视频的总时长（单位：秒）。 | ### Subtitle 对象 |参数 |类型 |描述 | |---|---|---| |`subtitle_text` |String |识别出的字幕文本。 | |`text_label` |String |文本类别标签（仅 `mode` 为 `Detailed` 模式返回）。

* `Subtitle`：字幕文本。

* `Others`：画面中的其他文字（如水印、台标、贴片等非字幕内容）。 | |`text_location` |Object |文本在画面中的像素坐标区域（仅 `mode` 为 `Detailed` 模式返回）。详见下文[Text location 对象](https://docs.volcengine.com/docs/6448/2386123#f752be14)。 | |`start_time` |Number |该字幕片段的起始时间（单位：秒）。 | |`end_time` |Number |该字幕片段的结束时间（单位：秒）。 | ### Text location 对象 |参数 |类型 |描述 | |---|---|---| |`top_left_x` |Integer |文本框左上角横坐标，单位 px。 | |`top_left_y` |Integer |文本框左上角纵坐标，单位 px。 | |`bottom_right_x` |Integer |文本框右下角横坐标，单位 px。 | |`bottom_right_y` |Integer |文本框右下角纵坐标，单位 px。 | #### 最终的完整任务信息示例（Detailed 模式） ```JSON { "success": true, "task_id": "amk-tool-video-ocr-123456789", "result": { "duration": 5.1, "subtitles": [ { "start_time": 1.2, "end_time": 3.5, "subtitle_text": "示例字幕文本", "text_label": "Subtitle", "text_location": { "top_left_x": 120, "top_left_y": 880, "bottom_right_x": 960, "bottom_right_y": 940 } }, { "start_time": 1.2, "end_time": 3.5, "subtitle_text": "节目LOGO", "text_label": "Others", "text_location": { "top_left_x": 30, "top_left_y": 30, "bottom_right_x": 200, "bottom_right_y": 80 } } ] }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见[错误码](https://docs.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "task_id": "", "request_id": "20240521120500XYZW12345", "error": { "code": "InvalidParameter", "message": "The parameter `video_url` is required.", "param": "video_url", "type": "BadRequest" } } ```