mistral-ocr

Mistral OCR

使用 Mistral 专用 OCR API 从图像和 PDF 中提取文本。无需外部依赖。

要求

此技能需要 Mistral API 密钥。如果你还没有，请按照 reference/getting-started.md 中的指南操作。

API 密钥

用户必须提供其 Mistral API 密钥。如果尚未提供，请向用户索取。

选项 1（推荐用于 AI Agent）： 用户直接在消息中提供密钥：

"Use this Mistral key: aBc123XyZ..."
"Convert this PDF to markdown, my API key is aBc123XyZ..."

选项 2： 环境变量 $MISTRAL_API_KEY

选项 3： Claude Code 设置（~/.claude/settings.json）

如果没有可用的密钥，请引导用户前往 console.mistral.ai 获取。

---

API 端点

所有文档处理均使用专用 OCR 端点：

POST https://api.mistral.ai/v1/ocr

模型： mistral-ocr-latest

---

功能

1. PDF → Markdown（直接处理，无需转换！）

curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr-latest",
    "document": {
      "type": "document_url",
      "document_url": "https://example.com/document.pdf"
    }
  }'

2. 图像 → 文本

支持 JPG、PNG、WEBP、GIF：

curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr-latest",
    "document": {
      "type": "image_url",
      "image_url": "https://example.com/image.jpg"
    }
  }'

3. 本地文件（Base64 数据 URL）

对于本地 PDF 或图像，请将其编码为 base64，并使用数据 URL。

始终使用 curl（适用于所有平台，包括通过 Git Bash 使用的 Windows）：

# For local PDF
BASE64=$(base64 -w0 document.pdf)
curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr-latest",
    "document": {
      "type": "document_url",
      "document_url": "data:application/pdf;base64,'"$BASE64"'"
    }
  }'

# For local images (PNG, JPG, etc.)
BASE64=$(base64 -w0 image.png)
curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-ocr-latest",
    "document": {
      "type": "image_url",
      "image_url": "data:image/png;base64,'"$BASE64"'"
    }
  }'

MIME 类型：

• PDF：data:application/pdf;base64,...
• PNG：data:image/png;base64,...
• JPG：data:image/jpeg;base64,...
• WEBP：data:image/webp;base64,...

4. 结构化 JSON 输出

对于发票、表单和表格，可在后续请求中要求输出 JSON，或使用 Document AI 注释。

---

响应格式

API 会直接返回 Markdown：

{
  "pages": [
    {
      "index": 0,
      "markdown": "# Document Title\n\nExtracted content here...",
      "images": [],
      "tables": [],
      "dimensions": {"dpi": 200, "height": 842, "width": 595}
    }
  ],
  "model": "mistral-ocr-latest",
  "usage_info": {"pages_processed": 1, "doc_size_bytes": 12345}
}

---

工作流

用户请求对图像或 PDF 进行 OCR

1. 获取 API 密钥——如果环境中没有，请向用户索取
2. 确定输入类型（URL 或本地文件）
3. 对于本地文件，始终使用临时文件方式（避免出现“Argument list too long”错误）：

# Cross-platform temp directory
TMPDIR="${TMPDIR:-${TEMP:-/tmp}}"

# Step 1: Encode file to base64
base64 -w0 "document.pdf" > "$TMPDIR/b64.txt"

# Step 2: Create JSON request file
echo '{"model":"mistral-ocr-latest","document":{"type":"document_url","document_url":"data:application/pdf;base64,'$(cat "$TMPDIR/b64.txt")'"}}' > "$TMPDIR/request.json"

# Step 3: Call API with -d @file (use actual key, not variable)
curl -s "https://api.mistral.ai/v1/ocr" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d @"$TMPDIR/request.json" > "$TMPDIR/response.json"

# Step 4: Extract markdown with node (NOT jq - not available on all systems)
node -e "const fs=require('fs'); const r=JSON.parse(fs.readFileSync('$TMPDIR/response.json')); console.log(r.pages.map(p=>p.markdown).join('\n\n---\n\n'))"

4. 使用 Write 工具保存为 .md 文件
5. 向用户确认文件位置

重要：跨平台兼容性

• 始终使用 curl（通过 Git Bash 可在 Windows 上运行）
• 请求正文始终使用 -d @file（可处理大型文件）
• 切勿使用 jq——改用 node 解析 JSON
• 临时文件使用 ${TMPDIR:-${TEMP:-/tmp}}（适用于所有系统）
• 在 Windows 上使用 node 解析之前，先将 response.json 复制到用户目录

---

使用示例

用户提出以下请求时：

用户请求	操作
“将此 PDF 转换为 markdown”	对 PDF 进行 OCR，并保存为 .md 文件
“从此图像中提取文本”	对图像进行 OCR，并返回文本
“给我一份此文档的 .md 文件”	进行 OCR，并保存为 .md 文件
“这份 PDF 写了什么？”	对 PDF 进行 OCR，并总结内容
“对这张收据进行 OCR”	提取文本，可选择整理为 JSON

---

错误处理

错误	原因	解决方案
401 Unauthorized	API 密钥无效	验证密钥，并引导用户查看 getting-started.md
400 Bad Request	文档无效	检查格式和 URL 是否可访问
3310 File fetch error	URL 无法访问	本地文件请使用 base64
Rate limit	请求过多	等待后重试

---

支持的格式

格式	支持情况
PDF	✅ 直接处理（无需转换）
PNG	✅ 直接处理
JPG/JPEG	✅ 直接处理
WEBP	✅ 直接处理
GIF	✅ 直接处理

无需外部依赖！ 与其他 OCR 解决方案不同，Mistral OCR 可直接处理 PDF，无需 pdftoppm、ImageMagick 或任何其他工具。

---

定价

截至 2025 年，Mistral OCR 的定价如下：

• 每 1,000 页 $2
• 使用 Batch API 可享受 50% 折扣

请在 mistral.ai/pricing 查看当前价格。

---

参考资料

• 入门指南 - 如何获取 API 密钥
• PDF 转 Markdown - PDF 转换示例
• 输出格式 - JSON、Markdown、纯文本
• 分步指南 - 包含示例的完整教程

---

由 Parlamento AI 提供的技能