POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/image-ocr

本 API 用于提交一个同步的图像文字识别（OCR）任务。支持标准版（简体中文和英文印刷体通用识别）与加强版（支持印刷体、手写体及 100+ 语种，并支持通用文字识别与关键词匹配识别两种任务类型），并返回每个文本块的位置坐标及置信度。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/document.png	待识别的图像 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。图像输入分辨率：短边不得超过 2160 px 长边不得超过 3840 px 文件大小：单张图片不得超过 10 MB。支持格式：支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic。图像质量建议：为保证最佳识别效果和性能，请注意：图像方向：避免使用旋转角度超过 30 度的图片，以防识别效果不佳或处理超时。文字密度：对于文字密度过高的图片（例如整页密排的文档），建议将其切分后再提交识别，以规避因处理内容过多而导致超时。
tool_version	String	否	standard	识别选用的模型版本，默认为 standard。 standard：标准版，支持通用印刷体文字识别，支持简体中文和英文语种。 max：加强版。相比于标准版，识别精准度更高，且适用范围更为广泛。具体说明如下：支持通用文字识别和关键词匹配文字识别。支持印刷体和手写体文字识别。支持 100+ 语种。中英文识别效果最优，其次为德语、法语、土耳其语、越南语、韩语、马来语、葡萄牙语、俄语、西班牙语、印尼语、泰语、意大利语、日语等 13 种常见语种。
task_type	String	否	spotting	识别任务类型，仅当 tool_version 为 max 时生效，默认为 spotting。 spotting：通用文字识别，按行识别文字内容和坐标，结果通过 ocr_result 返回。 keyword：关键词匹配识别，按 max_keywords 检索并返回匹配文本，结果通过 keyword_result 返回。
max_keywords	Array	否	["发票号码", "金额"]	关键词匹配列表，仅当 tool_version 为 max 且 task_type 为 keyword 时生效，此时为必填。数组中每个元素为一个待检索的关键词字符串，至少包含 1 个。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

示例 1：标准版通用识别

以下示例演示了如何提交一张图片进行标准版文字识别。

示例 2：加强版营业执照识别

以下示例演示了如何使用加强版 OCR 的关键词匹配功能，从一张营业执照图片中提取指定的关键字段信息。

响应说明

这是一个同步接口，处理结果将直接在本接口的响应体中返回。

响应参数

参数	类型	描述
success	Boolean	任务是否成功。 true：成功。请查看 result 字段以获取任务结果。 false：失败。请查看 error 字段以获取详细错误信息。
result	Object	包含图像处理结果的对象，仅在 success 为 true 时返回。详见下文 Result 对象。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。
task_id	String	任务的唯一标识。
task_type	String	任务类型。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
expires_at	Integer	任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。
queue_id	String	任务提交的目标队列 ID。

Result 对象

参数	类型	描述
ocr_result	Array	通用文字识别结果列表。标准版或加强版 task_type=spotting 时返回。每个 Object 代表一个识别出的文本块。详见下文 Ocr result 对象。
keyword_result	Object	关键词匹配识别结果。仅加强版 task_type=keyword 时返回。对象的 key 为您传入的关键词，value 为识别到的匹配文本（String 类型）。

Ocr result 对象

参数	类型	描述
content	String	识别出的文字内容。
confidence	Number	识别结果的置信度，取值范围为 [0, 1]，值越高表示结果越可信。仅标准版返回。
top_left_x	Number	文字框左上角的横坐标，单位为像素（px）。
top_left_y	Number	文字框左上角的纵坐标，单位为像素（px）。
bottom_right_x	Number	文字框右下角的横坐标，单位为像素（px）。
bottom_right_y	Number	文字框右下角的纵坐标，单位为像素（px）。

Error 对象

参数	类型	描述
code	String	具体的错误码，用于程序化识别错误类型。例如：InvalidParameter。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如：BadRequest。
message	String	对错误的详细描述，可用于开发调试。

响应示例

标准版 / 通用识别成功响应示例：

加强版关键词匹配识别（task_type=keyword）成功响应示例：

失败响应示例：

AI MediaKit