OCR API 文件:端點、模式與限制
本頁作為開發者的 OCR API 文件,將所有功能集中於一處:兩個端點、四種請求模式、限制與錯誤。API 會清理 OCR 引擎已產生的文字,但不讀取影像。
更新於

重點摘要
- 有兩種方法:POST /v1/chat/completions 與 GET /v1/models,使用 Bearer 金鑰進行驗證。
- 串流輸出、JSON 模式與函式呼叫遵循 OpenAI 聊天格式,模型 ID 為 uncensored。
- 限制:完整金鑰為 8 個並行請求與每分鐘 300 個請求,試用金鑰為 2 個並行請求與每分鐘 60 個請求,請求主體上限為 8 MB。
- 過載時的錯誤為 HTTP 429,代碼會告知你應降低速率或減少並行請求。
概覽與驗證
此服務為託管的 OpenAI 相容文字 API。本站上的用途為 OCR 作業的第二階段:取得 OCR 引擎產生的原始字串,並回傳乾淨的文字、結構化欄位或標記行。僅接受文字輸入。無影像、音訊或影片輸入或輸出,無嵌入向量,無微調。
所有功能位於同一個 Base URL https://api.llmocrapi.com/v1 下。驗證使用標準 Bearer 標頭:Authorization: Bearer YOUR_KEY。你可以在使用 Google 或電子郵件與密碼註冊後,於 API 金鑰頁面建立金鑰。端點後方的模型是由獨立供應商運行的單一開放權重模型。它不是任何模型供應商的官方 API,也不是跨供應商的路由器。其 ID 始終為 uncensored。
若想進行實作導覽而非僅參考文件,文件部分的快速入門會逐步引導你完成第一個請求。
端點總覽
| 方法與路徑 | 目的 |
|---|---|
GET /v1/models | 列出可用的模型。用它來進行低成本的金鑰檢查。 |
POST /v1/chat/completions | 在訊息列表上運行模型。支援串流輸出、JSON 模式與工具。 |
這就是全部的功能。由於它符合 OpenAI 的傳輸格式,任何允許你設定 Base URL 與金鑰的客戶端程式庫皆可運作。最快的快速檢查為:
curl https://api.llmocrapi.com/v1/models \
-H "Authorization: Bearer $LLMOCR_API_KEY"
有效的金鑰會回傳包含 uncensored 的模型列表。錯誤的金鑰會回傳驗證錯誤,告訴你問題出在金鑰而非請求主體。
請求參數
聊天完成請求需要 model 與 messages。以下可選欄位將傳遞給模型。
temperature與top_p:取樣控制。OCR 修復請使用temperature0,使相同輸入產生相同輸出。max_tokens:選填。若未指定,完成內容可使用提示詞剩餘的 100,000-token 上下文視窗空間。若希望限制每次呼叫的成本上限,請設定此值。stop:結束生成的字串。當要求輸出位於標記之間時很有用。seed:提高跨執行重複性。presence_penalty與frequency_penalty:直接傳遞。清理時請保持為零,因為懲罰可能促使模型更改重複的合法詞彙(如表格標頭)。stream、response_format、tools與tool_choice:將於接下來的三個章節說明。
上下文視窗計算提示詞與完成內容合計為 100,000 token,請求主體最大為 8 MB。實際上 token 限制會先達到。
串流回應
設定 "stream": true,API 會在生成文字時傳送 Server-Sent Events。串流輸出有助於互動式工具,例如編輯器中看著清理後的段落逐段出現。Token 用量會在串流結束時回報,因此你仍可記錄成本。
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.llmocrapi.com/v1", api_key=os.environ["LLMOCR_API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
stream=True,
messages=[{"role": "user", "content": "Fix this OCR text: th1s is a sam-\nple."}],
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
print("\ntokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
一個細節會影響吞吐量。串流請求會佔用其並行請求槽位,直到串流結束。若你的程式碼中途停止讀取並保持連線開啟,該槽位仍會保持忙碌。請明確關閉串流,或將其讀取至結束。
JSON 模式
JSON 模式要求模型以 JSON 物件而非散文回應。使用 response_format 啟用它,並在指示中描述鍵。
{
"model": "uncensored",
"temperature": 0,
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Return JSON with keys 'text' (cleaned string) and 'uncertain_lines' (array of integers)."},
{"role": "user", "content": "line one\nl1ne two\nline thr3e"}
]
}
謹慎解析。JSON 模式會規範輸出內容,但你仍應在資料存入資料庫之前驗證鍵名與型別。如果回應因 max_tokens 而被截斷,JSON 可能不完整,因此請提高上限或傳送較小的區塊。
函式呼叫
函式呼叫讓模型能夠要求你的程式執行某些動作,而非撰寫文字。在 OCR 工作中,常見的用法是回傳結構化的修正內容:模型會呼叫一個函式,傳入行號與替換內容,然後你的程式會套用這些修正。在 tools 陣列中定義工具,使用 tool_choice 選擇行為,並使用 role: "tool" 回傳結果為訊息。當進行串流輸出時,工具呼叫會以 tool_calls 增量形式逐步到達。
tools = [{
"type": "function",
"function": {
"name": "replace_line",
"description": "Replace one line of the OCR text with a corrected version.",
"parameters": {
"type": "object",
"properties": {
"line": {"type": "integer"},
"text": {"type": "string"},
},
"required": ["line", "text"],
},
},
}]
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "1: The inven-\n2: tory was com1leted."}],
tools=tools,
tool_choice="auto",
)
for call in resp.choices[0].message.tool_calls or []:
print(call.function.name, call.function.arguments)
參數會以 JSON 字串形式回傳。請解析這些參數、套用變更,並在繼續對話時,附加助手訊息與帶有相符 tool_call_id 的 role: "tool" 訊息。此模式能保持輸出 token 數量較低,因為模型只會回傳它變更的行。
適合文字清理的設定
參考資料搭配推薦的起始點會更有用,因此以下是參數在 OCR 修復中通常的組合方式。這些是根據任務行為的建議,並非量化的基準。
- 確定性修復:
temperature設為 0,無懲罰項,使用固定的seed。適用於你希望重新執行時能重現昨天輸出結果的檔案庫。 - 欄位擷取:
temperature0,response_format設為json_object,並設定max_tokens上限,略高於你預期的最大物件。 - 互動式檢視: 將
stream設為 true 並使用簡短的系統提示詞,讓編輯器能看到修正後文字出現,並可提前停止。 - 行級修復: 帶有
replace_line風格函式的工具,讓模型只回傳變更的內容。
訊息角色遵循一般慣例:system 用於固定指示,user 用於 OCR 文字,assistant 用於多輪對話中的先前回覆,以及 tool 用於函式結果。將指示放在系統訊息中,原始文字放在使用者訊息中。如果 OCR 文字本身包含看似指示的內容,例如掃描的標誌指示忽略先前的文字,這種分隔方式可讓模型更容易理解使用者訊息是待修復的資料,而非要遵循的指令。請在系統提示詞中明確說明這一點。
為每次呼叫保留 X-Request-Id 值的記錄。如果某個頁面回傳錯誤且你希望支援人員查看,這是支援人員需要的識別碼。
限制、標頭與錯誤
| 限制 | 完整金鑰 | 試用金鑰 |
|---|---|---|
| 並行請求 | 8 | 2 |
| 每分鐘請求數 | 300 | 60 |
| 最大主體大小 | 8 MB | 8 MB |
| 上下文視窗 | 100,000 token | 100,000 token |
回應內容包含 X-Request-Id(聯絡支援時請提供此值)、X-Balance-USD(你的剩餘額度)、X-RateLimit-Limit-Requests 與 X-RateLimit-Limit-Concurrency。
當超過限制時,API 會回傳 HTTP 429。錯誤程式碼 rate_limited 表示一分鐘內請求過多,請分散負載。程式碼 concurrency 表示同時進行中的請求過多,請降低 worker 數量。帶有 Retry-After: 5 標頭的 429 狀態碼表示暫時過載:等待五秒後再發送。失敗與被拒絕的請求不會計費,因此重試迴圈是安全的。
計費方式為按 token 計費:每 100 萬個輸入 token 為 $0.15,每 100 萬個輸出 token 為 $0.50,從預付額度扣除,該額度永不失效。請參閱 定價頁面 了解儲值金額與贈送額度。提示詞不會用於訓練。內容規則為單一嚴格限制:禁止涉及未成年人的性內容。政策相關問題請聯絡 支援。
更多指南
問答
API 提供哪些端點?
兩個:用於生成的 POST /v1/chat/completions 與用於模型列表的 GET /v1/models。兩者皆使用相同的 Bearer 金鑰。
是否支援串流輸出和函式呼叫?
可以。將 stream 設為 true 以啟用 SSE 並在結尾提供用量資訊,並使用 tools 與 tool_choice 進行函式呼叫,以 role tool 訊息形式回傳結果。
最大輸入大小為何?
上下文視窗為 100,000 token(含提示詞與完成內容),請求主體最多為 8 MB。
為什麼出現 429 錯誤?
你超出了每分鐘請求數(rate_limited)、並行請求數(concurrency),或遭遇暫時性過載(包含 Retry-After: 5)。請等待後重試。
只差一張表單,即可取得金鑰
建立帳號、複製金鑰、更改Base URL。這就是整個設定過程。