为了支持单元格内输出多个图片的能力，我们升级了 Table 结构的 Schema。本指南帮助你理解版本差异，选择合适的版本，以及平滑迁移到新版本。
版本说明 v1.3.0（旧版）— 单图支持
发布时间 ：原始版本特点 ：单元格只返回第一个图片字段 ：image_data（单对象）支持状态 ：✅ 长期支持（不计划下线）
v1.3.1（新版）— 多图支持
发布时间 ：2026-06-03特点 ：单元格支持返回多个图片字段 ：image_datas（数组）支持状态 ：✅ 推荐使用
重点 ：两个版本会长期共存，你可以根据业务需要选择。
如何选择版本 使用 v1.3.1（推荐） 如果你需要：
✅ 在一个单元格中获取多张图片
✅ 获取最新的特性和改进
✅ 享受更好的向前兼容性
保持使用 v1.3.0 如果你：
✅ 现有系统只需要单元格中的第一张图片
✅ 暂时不想修改代码
✅ 需要确保返回格式向后兼容
版本对比 Schema 结构变化 v1.3.0（旧版） ├── cells[] │ └── image_data (Object) │ ├── image_url │ └── mime_type v1.3.1（新版） ├── cells[] │ └── image_datas[] (Array) │ └── [0..N] │ ├── image_url │ └── mime_type
具体示例对比 { "cells" : [ { "row" : 0 , "col" : 0 , "text" : "Product Name" , "image_data" : { "image_url" : "https://webapi.textin.com/ocr_image/external/644a750608ccd302.jpg" , "mime_type" : "image/jpeg" } } ] }
{ "cells" : [ { "row" : 0 , "col" : 0 , "text" : "Product Name" , "image_datas" : [ { "image_url" : "https://webapi.textin.com/ocr_image/external/644a750608ccd302.jpg" , "mime_type" : "image/jpeg" }, { "image_url" : "https://webapi.textin.com/ocr_image/external/644a750608ccd303.jpg" , "mime_type" : "image/jpeg" } ] } ] }
关键差异 方面 v1.3.0 v1.3.1 字段名 image_dataimage_datas数据类型 Object Array 单元格图片数量 最多 1 张 多张 无图片时 字段存在，为 null 字段存在，为空数组 []
迁移步骤 1. 检查当前版本 查看你的代码中如何访问图片数据：
# 如果你的代码这样写，说明使用的是 v1.3.0 cell_image = cell.get( 'image_data' ) if cell_image: url = cell_image[ 'image_url' ]
2. 保留在 v1.3.0 修改 API 请求，添加 schema_version 参数：
import requests response = requests.post( 'https://api.textin.com/ocr/parse' , json = { 'file_url' : 'https://example.com/document.pdf' , 'schema_version' : '1.3.0' # 指定版本 } ) result = response.json()
3. 更新数据处理代码 for cell in result[ 'cells' ]: if 'image_data' in cell and cell[ 'image_data' ]: image_url = cell[ 'image_data' ][ 'image_url' ] process_image(image_url)
for cell in result[ 'cells' ]: if 'image_datas' in cell: for image_data in cell[ 'image_datas' ]: image_url = image_data[ 'image_url' ] process_image(image_url)
4. 测试验证
☐ 使用包含多个图片的测试表格验证
☐ 确认能获取到所有图片 URL
☐ 检查无图片单元格的处理逻辑
☐ 运行现有测试套件确保兼容性
代码示例 Python def extract_cell_images ( cell , schema_version = '1.3.1' ): """从单元格中提取所有图片 URL""" if schema_version == '1.3.1' : image_datas = cell.get( 'image_datas' , []) return [img[ 'image_url' ] for img in image_datas] elif schema_version == '1.3.0' : image_data = cell.get( 'image_data' ) if image_data: return [image_data[ 'image_url' ]] return [] raise ValueError ( f "Unsupported schema_version: { schema_version } " ) # 使用示例 response = call_api( schema_version = '1.3.1' ) for cell in response[ 'cells' ]: images = extract_cell_images(cell, schema_version = '1.3.1' ) print ( f "单元格 ( { cell[ 'row' ] } , { cell[ 'col' ] } ) 包含 { len (images) } 张图片" )
JavaScript function extractCellImages ( cell , schemaVersion = '1.3.1' ) { if ( schemaVersion === '1.3.1' ) { return ( cell . image_datas || []). map ( img => img . image_url ); } if ( schemaVersion === '1.3.0' ) { return cell . image_data ? [ cell . image_data . image_url ] : []; } throw new Error ( `Unsupported schema_version: ${ schemaVersion } ` ); } // 使用示例 const response = await callApi ({ schema_version: '1.3.1' }); response . cells . forEach ( cell => { const images = extractCellImages ( cell , '1.3.1' ); console . log ( `单元格 ( ${ cell . row } , ${ cell . col } ) 包含 ${ images . length } 张图片` ); });
常见问题
A: 如果不指定 schema_version，API 默认返回 v1.3.1 （最新版本）。
A: 暂时不计划下线 v1.3.0，我们会长期支持两个版本。如有变化会提前通知。
A: 不能。一个 API 请求只能指定一个 schema_version，整个响应都遵循该版本的格式。
v1.3.0 image_data = cell.get( 'image_data' ) if image_data is None : print ( "该单元格无图片" )
v1.3.1 image_datas = cell.get( 'image_datas' , []) if not image_datas: print ( "该单元格无图片" )
A: 不会。指定 schema_version=1.3.0 的请求永远返回 v1.3.0 格式，保证向后兼容。
A: 通过检查单元格中是否存在 image_data 或 image_datas 字段：
有 image_data（Object）→ v1.3.0
有 image_datas（Array）→ v1.3.1
Q: 无效的 schema_version 会发生什么？
A: 返回 400 Bad Request 错误，错误信息会说明支持的版本列表。{ "code" : 400 , "message" : "Invalid schema_version: 1.2.0. Supported versions: 1.3.0, 1.3.1" }
迁移时间表 阶段 时间 内容 发布 2026-06-10 v1.3.1 版本发布 过渡 2026-06-10 ~ v1.3.0 和 v1.3.1 并行支持 下线 待定 如计划下线 v1.3.0 会提前通知
相关链接 解析配置详解 了解如何配置 schema_version 参数
API 参考 完整的 API 参数与响应 Schema
支持与反馈 遇到问题或需要帮助？
如有任何问题或遇到迁移困难，欢迎随时联系我们！ 
