token 是什么，为什么必须提供唯一 token？
token 是解析任务的唯一索引，用于查询状态和获取结果。原生 API 调用时需要自行保证唯一性，推荐使用 UUID；如果复用未完成任务的 token，可能返回 Token_Duplicated。
应该使用 UniParser-Tools 还是 UniParser-API？
优先使用 UniParser-Tools。它会自动处理 token 生成、任务提交、轮询和结果获取，适合脚本、批处理和 notebook。只有在需要直接控制 HTTP 请求、鉴权、回调、并发或字段开关时，才建议使用原生 UniParser-API。
sync=true 和 sync=false 怎么选？
sync=true 会在提交请求中等待解析完成，适合小文件、调试和示例。大文件、批处理或高并发任务建议使用默认异步模式 sync=false，提交后保存返回的 token，稍后调用结果接口获取内容。
文件超过限制怎么办？
访客标准账号默认限制为 200 MB、2000 页；付费用户或已开通高额度的账号默认限制为 300 MB、6000 页，具体以 API 申请和账号配置为准。超过限制时可以压缩或拆分 PDF，或申请更高额度。
触发 429 限速怎么办？
当前 rate limit 使用近似滑动窗口机制。触发限速时接口会返回 429，表示当前用户、接口或全局入口的请求频率超过了服务端配置。
逐用户生效的限速主要覆盖两类 API：
- 解析请求 API：例如提交 PDF、URL、截图/图片解析的接口，会按照账号配置中的速率
S 限速。
- 结果获取 API：例如获取状态、格式化结果、段落或视图结果的接口，也会逐用户限速；这类接口的限速通常比解析提交接口宽松很多，便于轮询和批量取结果。
另外，部分管理类、信息获取类或公共入口 API 会有全局限速。全局限速不区分用户，主要用于避免异常流量导致系统后端过载。
客户端侧建议使用令牌桶控制并发请求：令牌以速率 R 放入桶中，桶容量为 B；每次请求先消耗一个令牌，没有令牌时排队或等待。这样可以平滑批量请求，避免瞬时并发打满服务端限速。
令牌生成器（速率 R）
|
v （不断放入令牌）
+-------------+
| 令牌桶 | 最大容量 B
| o o o |
+-------------+
|
v （请求到达，消耗令牌）
[ 待发送请求 ] --------> [ 允许通过 ]
如果仍然频繁触发 429，请降低提交频率和并发数，并在重试时增加退避等待。批量任务建议排队异步提交；如果业务需要更高吞吐，可以申请更高请求频率限制。
content、objects、pages_dict、pages_tree 有什么区别？
content 返回格式化后的全文，适合阅读、检索和 LLM 输入。objects 返回扁平语义块列表，适合按块处理坐标、类型和文本。pages_dict 按页返回扁平布局。pages_tree 按页返回树形结构，适合需要父子层级关系的场景。
表格结果应该看哪个字段？
如果只需要可读文本，通常直接获取 content，并把 table 输出格式设为 markdown 或 html。如果需要结构化表格对象，请查看 objects、pages_dict 或 pages_tree 中的表格块。table=1（fast）通常需要结合 structure、placeholders、contents 还原表格；table=2（hq）通常在 structure 中直接包含完整表格数据。
textual 和 table 都要设置吗？
需要根据目标分别设置。table 控制表格区域的结构识别和单元格内容识别；表题、表注、正文段落等主要受 textual 控制。如果希望正文和表格都尽量高质量，通常同时设置 textual=2 和 table=2。
What is token, and why must it be unique?
token is the unique index for a parsing task and is used to query status and fetch results. Native API callers must ensure uniqueness, preferably with UUIDs. Reusing a token for an unfinished task may return Token_Duplicated.
Should I use UniParser-Tools or UniParser-API?
Use UniParser-Tools by default. It handles token generation, task submission, polling, and result fetching for you, which is suitable for scripts, batch jobs, and notebooks. Use the native UniParser-API only when you need direct control over HTTP requests, authentication, callbacks, concurrency, or field switches.
How should I choose between sync=true and sync=false?
sync=true waits for parsing to finish in the submit request. It is useful for small files, debugging, and examples. For large files, batch jobs, or high-concurrency workloads, use the default async mode sync=false, store the returned token, and fetch the result later.
What should I do if my file exceeds the limit?
Visitor standard accounts are limited to 200 MB and 2000 pages by default. Paid users or accounts with higher quotas default to 300 MB and 6000 pages, with the actual quota determined by the API application and account provisioning configuration. Compress or split the PDF, or request a higher quota.
What should I do after a 429 rate-limit response?
The current rate limit is implemented as an approximate sliding-window mechanism. A 429 response means the request rate has exceeded the server-side limit for the current user, endpoint, or global entry point.
User-level rate limits mainly apply to two groups of APIs:
- Parsing request APIs: endpoints that submit PDF, URL, snip, or image parsing tasks. These are limited according to the account rate
S.
- Result retrieval APIs: endpoints that fetch task status, formatted results, paragraphs, or view data. These are also limited per user, but their limits are usually much more tolerant than the parsing submission rate so clients can poll and fetch batch results.
Some management, information retrieval, or public-entry APIs also have global rate limits. Global limits are not user-specific; they protect the backend from overload caused by abnormal traffic.
For client-side concurrency control, we recommend using a token-bucket algorithm. Tokens are added to the bucket at rate R, and the bucket capacity is B. Each request consumes one token before it is sent; if no token is available, the request should wait or remain queued. This smooths bursty batch traffic and avoids hitting server-side rate limits.
Token generator (rate R)
|
v (adds tokens continuously)
+-------------+
| Token bucket | max capacity B
| o o o |
+-------------+
|
v (incoming request consumes a token)
[ Pending request ] --------> [ Allowed ]
If you still hit 429 frequently, reduce submission frequency and concurrency, and add backoff before retrying. For batch jobs, queue tasks and submit them asynchronously. If your business requires higher throughput, request a higher rate limit.
What is the difference between content, objects, pages_dict, and pages_tree?
content returns formatted full-document text, suitable for reading, search, and LLM input. objects returns a flat semantic block list for block-level coordinates, types, and text. pages_dict returns flattened page-level layouts. pages_tree returns page-level trees when parent-child hierarchy is needed.
Which field should I use for table results?
If you only need readable text, fetch content and set the table output format to markdown or html. If you need structured table objects, inspect table blocks in objects, pages_dict, or pages_tree. With table=1 (fast), you usually reconstruct tables from structure, placeholders, and contents; with table=2 (hq), structure usually contains the complete table data directly.
Should I set both textual and table?
Set them according to what you need. table controls table-region structure recognition and cell-content recognition; table captions, table footnotes, and body paragraphs are mainly controlled by textual. If you want both body text and tables to use higher quality, usually set both textual=2 and table=2.
