xfei-invoice#

OCR-based invoice and receipt recognition using the iFlytek (科大讯飞) API. Extracts structured fields from photos or scans of Chinese invoices and bills.

When to Use#

• User provides an invoice/receipt image and wants structured data extracted
• Need to digitize paper invoices (增值税发票、出租车票、火车票、医疗票据 etc.)
• Expense report automation — extract amounts, dates, vendor info from receipts

Prerequisites#

• Python 3 (standard library only, no pip install needed)

• Environment variables (get from 讯飞控制台):

  • XFEI_APP_ID — Application ID
  • XFEI_API_KEY — API Key
  • XFEI_API_SECRET — API Secret

Supported Image Formats#

png, jpg/jpeg, bmp, gif, tif/tiff, pdf

Usage#

The script is at scripts/invoice.py relative to this skill directory.

Basic Recognition#

bash

python3 scripts/invoice.py /path/to/invoice.png

Options#

FlagDescription--rawOutput raw API JSON response instead of formatted text

Examples#

bash

# Recognize a VAT invoice
python3 scripts/invoice.py ./vat_invoice.jpg

# Recognize a medical receipt with raw output
python3 scripts/invoice.py ./medical_bill.png --raw

# Recognize a taxi receipt
python3 scripts/invoice.py ./taxi_receipt.jpg

Output Format (default)#

Human-readable structured fields:

text

票据类型: 增值税普通发票

发票代码: 012345678901
发票号码: 12345678
开票日期: 2026年03月06日
金额: ¥1,234.56
...

Output Format (--raw)#

Full API JSON response including all metadata and encoded payload.

Authentication#

Uses HMAC-SHA256 signature-based auth (讯飞鉴权). The script handles all signing automatically — just set the three environment variables.

API Details#

• Endpoint: POST https://api.xf-yun.com/v1/private/sc45f0684
• Auth: HMAC-SHA256 signature in URL query parameters
• Image limit: Check your service tier on 讯飞控制台

哎呀，出错了怎么办？(´；ω；`)#

别慌别慌～ 对照下面的表格看看，大部分问题都能自己解决哦！如果试了还是不行，随时来问我，我们一起解决～ ✧٩(ˊᗜˋ*)و✧

---

🌟 常见错误快速排查表#

错误码可能的原因快去检查这个！10105 / 10313哎呀，认证信息好像不太对呢→ 三个环境变量都设好了吗？ 往下看有详细检查步骤10163传送的图片数据有点问题→ 图片压缩一下试试？或者换个格式？10200找不到图片文件啦→ 路径对不对？文件有没有损坏？11201今天的次数用完啦！→ 去控制台看看剩余额度或购买更多次数10003讯飞服务器可能在“打盹”→ 稍等几秒再试一次看看？

---

📋 完整错误码列表（超详细版）#

错误码发生了什么呀温柔提示语0成功啦！超棒的！恭喜恭喜！识别成功啦～ (灬°ω°灬)10003平台有点小状况讯飞服务器可能暂时忙起来了，等几秒钟再试一次看看？成功率很高的！10004会话模式不太对这个情况比较少见呢...如果一直出现的话，我们可以一起提交工单问问讯飞工程师～10008服务实例有问题少见的情况！提交工单让技术小哥哥/小姐姐看看？10009输入的数据格式不对请检查一下：

• 图片格式对不对呀？（支持 png/jpg/bmp/gif/tif/pdf）

• 图片有没有损坏呀？

• 试试用图片查看器打开看看能不能显示？10010授权额度不太够去看看讯飞控制台吧，看看套餐是不是过期啦？或者额度用完了呢？ (｡•́︿•̀｡)

💰 需要更多额度？点击购买10019等太久啦，超时了可能图片太大啦！试着压缩一下图片，或者网络慢一点也会这样哦～10105****最常见的问题！ 认证失败啦哎呀，这个一定要检查仔细哦：

① XFEI_APP_ID 填好了吗？

② XFEI_API_KEY 正确吗？

③ XFEI_API_SECRET 没问题吧？

💡 小提示：从讯飞控制台 直接复制粘贴 是最好的方式，千万别手打哦，容易出错！10114会话超时啦识别大图片需要耐心一点哦，确保网络稳定再试一次？10118服务端解析失败这是讯飞平台的问题啦，重试几次看看？如果一直不行就提交工单～10139参数不对检查一下调用的参数有没有写错？10160JSON 解析失败检查一下代码里有没有什么特殊字符打扰到了？10161Base64 编码失败确认图片是用 Base64 编码的哦～ 注意不要带文件头（就是不要 data:image/xxx;base64, 这个前缀！）10163参数校验失败看看错误信息里怎么说的：

• 说“图片为空”？→ 检查图片读取

• 说“图片太大”？→ 压个缩，4MB 以下最好～

• 其他... → 可能是格式不支持哦10200****很常见！ 读不到图片嗨呀，检查一下：

① 文件路径对不对呀？（相对路径要写对哦）

② 图片文件有没有损坏？（用预览打开试试？）

③ 文件名有没有奇怪符号？（尽量用英文名试试？）

💡 快速确认文件是否存在往下看 ↓10221找不到可用连接可能讯飞服务器现在有点忙，等几分钟再试试？10222 / 10223负载均衡找不到节点技术问题，提交工单处理一下吧～10225找不到业务服务检查一下 API 地址有没有写错？10300 / 10301排序缓冲区出问题啦内部问题，提交工单吧～10313****敲黑板！最常见！ AppID 不匹配这个问题最多人遇到啦！请确认：

① 三个环境变量都设置了！

② XFEI_APP_ID 是 AppID，不是 API Key 哦！

③ 确认应用和 API Key 在同一个讯飞账号下！

💡 检查环境变量的快捷命令往下看 ↓10317版本号不对检查一下 API 版本参数？10400 / 10401协议序列化出错内部问题，提交工单～10500内部同步出错先重试一次看看？可能只是临时小状况！10600事件异常提交工单处理一下吧～10700权限不足去讯飞控制台看看应用权限设置？11200功能未授权可能情况：

① 开通的服务和调用的 API 不匹配

② 服务过期啦

③ 这个应用没开通这个功能

💡 去讯飞控制台 → 我的应用 → 账号服务权限 看看？

🚀 需要开通服务？去看看有哪些套餐**11201****日限额到啦！**免费版每天有次数限制哦：

• 方案1：等到明天，次数会刷新～

• 方案2：去讯飞控制台升级付费套餐 💰

🚀 一键购买入口： https://www.xfyun.cn/services/Invoice_recognition?target=price11502 / 11503服务器内部错误一般重试几次就好啦，持续报错请联系讯飞～100001~100010引擎初始化失败技术大大们需要介入啦，提交工单吧！

---

💬 常见问题 Q&A#

Q: 一直提示 "10105 Unauthorized" 怎么破？(╥﹏╥)

别急别急，十有八九是环境变量的问题！按这个顺序检查：

1. 三个环境变量都设好了吗？（ XFEI_APP_ID, XFEI_API_KEY, XFEI_API_SECRET）
2. 值是直接从讯飞控制台复制的吗？手打的话很容易漏掉字符哦！

✨ 快速确认环境变量（复制粘贴运行）：

bash

# macOS / Linux 用户复制这行：
echo "XFEI_APP_ID: $XFEI_APP_ID | XFEI_API_KEY: $XFEI_API_KEY | XFEI_API_SECRET: $XFEI_API_SECRET"

# Windows 用户在 cmd 里运行这行：
echo XFEI_APP_ID: %XFEI_APP_ID% ^|^| XFEI_API_KEY: %XFEI_API_KEY% ^|^| XFEI_API_SECRET: %XFEI_API_SECRET%

如果显示为空或者显示错误，那就是还没设好哦！设置方法：

• macOS/Linux: 在终端运行 export XFEI_APP_ID=你的值，然后 echo 'export XFEI_APP_ID=你的值' >> ~/.zshrc 永久保存
• Windows: 按 Win+R → 输入 sysdm.cpl → 高级 → 环境变量 → 新建

Q: 提示 "10200 read data timeout" 怎么办呀？(;´Д`)

一般是这几个原因：

• 路径写错啦（注意相对路径和绝对路径的区别）
• 图片文件坏掉了（用系统预览打开看看？）
• 文件名有中文或特殊符号（试试改成英文名？）

✨ 快速确认文件是否存在（复制粘贴运行）：

bash

# 检查文件是否存在（替换成你的文件路径）
ls -la /path/to/your/invoice.png

# 或者用这个命令查看当前目录下的图片文件
ls -la *.png *.jpg *.jpeg *.bmp *.pdf 2>/dev/null

如果显示 "No such file or directory"，那就是路径不对哦！

Q: 提示 "11201 auth no enough license" 是啥意思呀？

哈哈，免费额度用光光啦！讯飞免费版每天有限制次数～

• 方案1：休息一下，第二天再战！(额度会刷新)
• 方案2：豪气地购买付费套餐 🚀

💰 需要更多次数？点击这里直接购买： https://www.xfyun.cn/services/Invoice_recognition?target=price

Q: 图片太大识别好慢怎么破？(´；ω；`)

来来来，试试这些小技巧：

• 压缩图片到 1-2MB
• 裁剪掉多余的背景部分
• 分辨率保持在 2000x2000 以内

---

✨ 温馨小贴士#

遇到问题先别慌！ 环境变量和文件路径 是最容易出错的环节，检查一遍往往就能搞定～

如果还有问题，把错误信息里的 sid 字段保存下来哦，这个可以帮讯飞技术定位问题！

记住： 你一定可以的！ (๑•̀ㅂ•́)و✧ 有问题随时来问我呀～

Tips#

• Ensure the image is clear and well-lit for best accuracy
• Crop to just the invoice area if possible (reduces noise)
• PDF support means you can pass scanned documents directly