Doc2X API v2 图片接口文档
从文件到本地结果
- 准备清晰、可打开的 JPG/PNG；确认可以将该文件交给开放平台处理。
- 需要立即等待一个响应时使用同步接口；需要保存任务 ID、稍后查询时使用异步提交接口。二者都发送原始二进制，不用 multipart/form-data。
- 异步提交成功后保存
data.uid，每 1–3 秒 GET 状态并设置总等待期限。processing继续等；failed查看detail；外层code不是success时先排查接口错误。不要重复 POST 作为轮询。 - 成功后保存
data.result、逐页md和可用的convert_zip图片包。它可能为空；下面示例为结构示意，不附伪造图片包。 - 下载并核对文字、表格、公式与图片引用。API 内容临时保留约 24 小时；本地等候超时不代表远端取消，续查已有 ID 后再决定是否重新提交。
鉴权、错误码与限额边界参见 PDF API。解析质量分或 HTTP 200 不能代替结果复核；图片解析不等于图片翻译编辑器。
基础信息
URL: https://v2.doc2x.noedgeai.com
请直连访问 API 接口，中国内地以外地区可能有较大网络波动，导致上传文件断流严重
批量处理前在开放平台核对账户配额和当前速率限制；不要把旧说明中的“30 张/30s”当作所有账户可保证的并发量。使用异步任务逐个提交并保存任务 ID，再按返回状态控制队列。
Authorization 鉴权
先在开放平台获取 API Key 并确认额度；YOUR_DOC2X_API_KEY 是占位符，不是可用密钥。
在 HTTP 请求头加入：
text
Authorization: Bearer YOUR_DOC2X_API_KEYPOST /api/v2/parse/img/layout 图片 layout
含布局识别的图片 OCR 接口，效果和 /parse/pdf 一致，支持文字，公式，多栏，表格，图片的解析和提取（主要适用于文档图片和类文档图片）
此接口为同步调用接口
图片请求体上限为 7 MiB（7,340,032 bytes）；这是开放平台图片 API 限制，CLI 的 3 MiB 是另一入口。
计价方式：1 张图片 = 1 页 PDF 解析（1:1），会同等消耗通用解析页数
请求参数
| 名称 | 位置 | 类型 | 必选 | 说明 |
|---|---|---|---|---|
| body | body | binary | 是 | 请求体为 img(jpg/png) 的二进制，最大不超过 7 MiB |
请求示例
bash
curl -X POST 'https://v2.doc2x.noedgeai.com/api/v2/parse/img/layout' \
--header 'Authorization: Bearer YOUR_DOC2X_API_KEY' \
--data-binary '@test.jpg'注意，--data-binary 并不是 formdata，而是以二进制形式写入 body 中，python 代码如下：
python
import requests
url = 'https://v2.doc2x.noedgeai.com/api/v2/parse/img/layout'
headers = {'Authorization': 'Bearer YOUR_DOC2X_API_KEY'}
with open('test.jpg', 'rb') as file:
response = requests.post(url, headers=headers, data=file, timeout=(10, 90))
response.raise_for_status() # 使用data
print(response.text)返回示例
json
{
"code": "success",
"data": {
"convert_zip": null,
"result": {
"pages": [
{
"page_width": 1000,
"page_height": 1000,
"md": "123456789"
}
]
},
"uid": "01940000-0000-0000-0000-111111111"
}
}convert_zip 解压后的文件结构
text
.
|--images # 图片资源文件
|--example1.jpg
|--example2.jpgPOST /api/v2/async/parse/img/layout 异步图片 layout 提交任务
含布局识别的图片 OCR 接口，效果和 /parse/pdf 一致，支持文字，公式，多栏，表格，图片的解析和提取（主要适用于文档图片和类文档图片）
此接口为异步调用接口
图片请求体上限为 7 MiB（7,340,032 bytes）；这是开放平台图片 API 限制，CLI 的 3 MiB 是另一入口。
计价方式：1 张图片 = 1 页 PDF 解析（1:1），会同等消耗通用解析页数
异步图片请求参数
| 名称 | 位置 | 类型 | 必选 | 说明 |
|---|---|---|---|---|
| body | body | binary | 是 | 请求体为 img(jpg/png) 的二进制，最大不超过 7 MiB |
异步图片请求示例
bash
curl -X POST 'https://v2.doc2x.noedgeai.com/api/v2/async/parse/img/layout' \
--header 'Authorization: Bearer YOUR_DOC2X_API_KEY' \
--data-binary '@test.jpg'注意，--data-binary 并不是 formdata，而是以二进制形式写入 body 中，python 代码如下：
python
import requests
url = 'https://v2.doc2x.noedgeai.com/api/v2/async/parse/img/layout'
headers = {'Authorization': 'Bearer YOUR_DOC2X_API_KEY'}
with open('test.jpg', 'rb') as file:
response = requests.post(url, headers=headers, data=file, timeout=(10, 90))
response.raise_for_status() # 使用data
print(response.text)异步图片返回示例
json
{
"code": "success",
"data": {
"uid": "01940000-0000-0000-0000-111111111"
}
}GET /api/v2/parse/img/layout/status 异步图片 layout 处理状态
异步图片处理状态请求参数
请求头
| 名称 | 描述 | 示例值 |
|---|---|---|
| Authorization | Api key | Bearer YOUR_DOC2X_API_KEY |
请求体
| 名称 | 位置 | 类型 | 必选 | 说明 |
|---|---|---|---|---|
| uid | query | string | 是 | 异步任务的 id |
异步图片处理状态请求示例
bash
curl --request GET 'https://v2.doc2x.noedgeai.com/api/v2/parse/img/layout/status?uid=01920000-0000-0000-0000-000000000000' \
--header 'Authorization: Bearer YOUR_DOC2X_API_KEY'异步图片处理状态返回示例
处理完成的情况
json
{
"code": "success",
"data": {
"status": "success",
"result": {
"pages": [
{
"url": "01952205-b26f-7930-93c1-103c88156729_0.jpg",
"page_idx": 0,
"page_width": 1080,
"page_height": 4322,
"md": "<!-- Media -->\n\n<img src=\"01952205-b26f-7930-93c1-103c88156729_0_0_59_1080_4221_0.jpg\"/>\n\n<!-- Media -->"
}
]
},
"convert_zip": null
}
}失败的情况
json
{
"code": "parse_error",
"msg": "解析错误"
}等待的情况
json
{
"code": "success",
"data": {
"status": "processing"
}
}异步任务 convert_zip 解压后的文件结构
text
.
|--images # 图片资源文件
|--example1.jpg
|--example2.jpg保存 Markdown 与图片资源
先将成功的同步响应或异步状态响应保存为 image-response.json。下面 Python 3.10+ 代码只处理本地文件，不发网络请求；保存为 save_image_result.py 后运行 python save_image_result.py。
python
import base64
import io
import json
import zipfile
from pathlib import Path
def save_image_response(body, output_dir):
if body.get("code") != "success":
raise ValueError(f"API error: {body.get('code')}")
data = body["data"]
if "status" in data and data["status"] != "success":
raise ValueError(f"Not a completed result: {data['status']}")
result = data["result"]
encoded = data.get("convert_zip")
archive = base64.b64decode(encoded, validate=True) if encoded else None
if archive is not None and not zipfile.is_zipfile(io.BytesIO(archive)):
raise ValueError("convert_zip is not a ZIP; retain response and check the service format")
out = Path(output_dir)
out.mkdir(exist_ok=False)
(out / "result.json").write_text(
json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
(out / "result.md").write_text("\n\n".join(
page.get("md", "") for page in result.get("pages", [])), encoding="utf-8")
if archive is not None:
(out / "images.zip").write_bytes(archive)
return out
if __name__ == "__main__":
body = json.loads(Path("image-response.json").read_text(encoding="utf-8"))
print(save_image_response(body, "image-output"))随后查看 image-output/result.md，必要时用 unzip -l image-output/images.zip 检查资源清单，再解压到新目录并按 Markdown 中的实际相对路径放置。不要因为包里有图片，就假设所有页面引用都已可用。不要将网页预览或表格 HTML 当成已导出的 XLSX。
| 现象 | 排查 |
|---|---|
| 401/403、额度不足、429 | 检查开放平台 Key/余额/速率，降低队列并发；不改用客户端 Token。 |
| 图片格式/大小错误 | 核对实际 JPG/PNG 内容与 7 MiB 上限；先本地转格式或缩小文件。 |
failed 或状态过期 | 记录 uid 和 detail，检查本地备份；不要无限创建新任务。 |
| Base64 或 ZIP 校验失败 | 保留脱敏错误及原响应，确认服务格式，不把任意解码数据强行解压。 |
| Markdown 图片不见了 | 比较实际引用与解压目录，保留相对路径并检查文件是否保存完整。 |