OCRRouter

GPT API docs

How OCRRouter calls GPT, what the upstream returns field by field, and how that becomes Markdown and JSON blocks.

Overview

GPT is OpenAI's multimodal model family. OCRRouter sends the file with a fixed transcription prompt through the Responses API and gets Markdown back.

The model returns one text answer for the whole file. OCRRouter asks it to mark each page and splits on those marks.

Price and limits

Model ID
openai/gpt
Price
11 credits / page ($11 per 1,000 pages)
Max pages per request
100
Inputs
PDF; Images; Sent inline as base64 data URLs
Languages
50+ languages
Positions (bbox)
No, text only
  • Up to 100 pages per document in OCRRouter
  • OpenAI accepts files up to 50 MB per request

You pay only for pages that succeed. A failed attempt that falls back to another model is not charged. See pricing.

How OCRRouter calls it

Endpoint
POST https://api.openai.com/v1/responses
Model
OPENAI_OCR_MODEL, default gpt-5-mini
Request
One user message: input_file (PDF as data URL) or input_image (image data URL), then input_text with the OCR prompt
Fallback
No OpenAI key: Chat Completions on AIHubMix (default gpt-6.1-terra) or OpenRouter (default openai/gpt-6.1-terra)

Options

What OCRRouter sets on the upstream call. You choose the model, format and pages in your request; vendor-specific options are not passed through.

Prompt
Fixed: transcribe every page exactly as Markdown, LaTeX for formulas, a <!-- page:N --> line before each page, no code fence
temperature
Not set on the Responses call; 0 on the gateway call
max_output_tokens
Not set: model default
Client options
Clients cannot pass OpenAI-specific options through OCRRouter

Raw response fields

Every field the upstream documents, with its type and meaning taken from the vendor's own reference. Fields marked "read by OCRRouter" are the ones our connector uses; the rest are listed so you know what the engine produces.

OpenAI Responses API response

Response object from POST /v1/responses. Fields follow OpenAI's API reference.

Source: OpenAI Responses API: response object, retrieved 2026-11-19

idstring
Unique ID of the response.Example: "resp_67ccd2bed1ec8190..."
objectstring
Always response.Example: "response"
created_atnumber
Unix time in seconds when the response was created.
statusstring
completed, failed, in_progress or incomplete.Example: "completed"
errorobject | null
Error details when the model failed to respond.
incomplete_detailsobject | null
Why the response is incomplete.
instructionsstring | null
System or developer message inserted first in context.
max_output_tokensinteger | null
Upper bound on generated tokens, including reasoning tokens.
modelstring
Model ID used for the response.
outputarray, read by OCRRouter
Items generated by the model; length and order depend on the response.
output[].typestring
Item type; message for text output (reasoning items may also appear).Example: "message"
output[].idstring
ID of the output message.
output[].rolestring
Always assistant for output messages.
output[].statusstring
in_progress, completed or incomplete.
output[].contentarray, read by OCRRouter
Content parts of the output message.
output[].content[].typestring, read by OCRRouter
output_text for text (refusal is the other kind).Example: "output_text"
output[].content[].textstring, read by OCRRouter
Text output from the model.
output[].content[].annotationsarray
Annotations on the text, such as citations.
output_textstring
SDK-only convenience joining all output_text parts; not in the raw HTTP body.
parallel_tool_callsboolean
Whether tool calls may run in parallel.
previous_response_idstring | null
ID of the previous response in a multi-turn chain.
reasoningobject | null
Reasoning settings for reasoning models.
service_tierstring | null
Processing tier used.
temperaturenumber | null
Sampling temperature used.
textobject
Text output format settings, plain text or structured JSON.
tool_choicestring | object
How the model picked tools.
toolsarray
Tools the model could call.
top_pnumber | null
Nucleus sampling value used.
truncationstring | null
Truncation strategy, auto or disabled.
usage.input_tokensinteger
Input tokens.
usage.input_tokens_details.cached_tokensinteger
Input tokens served from cache.
usage.output_tokensinteger
Output tokens.
usage.output_tokens_details.reasoning_tokensinteger
Output tokens spent on reasoning.
usage.total_tokensinteger
Total tokens used.
userstring
End-user identifier sent with the request.
metadataobject
Key-value pairs attached to the response.

Shape from OpenAI's Responses API reference example; text replaced with OCR output, request echo fields left out.

{"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452…","object": "response","created_at": 1741476542,"status": "completed","error": null,"incomplete_details": null,"model": "gpt-5-mini","output": [{"type": "message","id": "msg_67ccd2bf17f0819081ff3bb2cf6508e6","status": "completed","role": "assistant","content": [{"type": "output_text","text": "<!-- page:1 -->\n# Invoice 1042\n...","annotations": []}]}],"usage": {"input_tokens": 1290,"input_tokens_details": { "cached_tokens": 0 },"output_tokens": 412,"output_tokens_details": { "reasoning_tokens": 0 },"total_tokens": 1702}}

Gateway response: Chat Completions

Used when no direct vendor key is set. OCRRouter calls POST /chat/completions on AIHubMix or OpenRouter, which return OpenAI's chat completion object. Fields follow OpenAI's reference.

Source: OpenAI chat completion object, retrieved 2026-11-19

idstring
Unique ID of the chat completion.Example: "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG"
objectstring
Always chat.completion.Example: "chat.completion"
createdinteger
Unix time in seconds when the completion was created.Example: 1741570283
modelstring
Model used for the completion.
choicesarray, read by OCRRouter
Completion choices; more than one only when n > 1.
choices[].indexinteger
Position of the choice in the list.Example: 0
choices[].message.rolestring
Role of the message author, assistant.Example: "assistant"
choices[].message.contentstring | null, read by OCRRouter
Text of the message.
choices[].message.refusalstring | null
Refusal message from the model, if any.
choices[].message.annotationsarray
Annotations such as web search citations, when applicable.
choices[].message.tool_callsarray
Tool calls generated by the model.
choices[].finish_reasonstring
Why generation stopped: stop, length, content_filter, tool_calls or function_call.Example: "stop"
choices[].logprobsobject | null
Log probability information for the choice.
usage.prompt_tokensinteger
Tokens in the prompt.
usage.completion_tokensinteger
Tokens in the generated completion.
usage.total_tokensinteger
Prompt plus completion tokens.
usage.prompt_tokens_detailsobject
Breakdown of prompt tokens, such as cached tokens.
usage.completion_tokens_detailsobject
Breakdown of completion tokens, such as reasoning tokens.
service_tierstring | null
Processing tier used for the request.
system_fingerprintstring
Backend configuration the model ran with.
errorobject, read by OCRRouter
Not part of OpenAI's object. Gateways may return an error object in a 200 body; OCRRouter treats it as a failure.

Shape from OpenAI's chat completion object example; content replaced with OCR output, values shortened.

{"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG","object": "chat.completion","created": 1741570283,"model": "MODEL","choices": [{"index": 0,"message": {"role": "assistant","content": "<!-- page:1 -->\n# Invoice 1042\n...","refusal": null,"annotations": []},"logprobs": null,"finish_reason": "stop"}],"usage": {"prompt_tokens": 1117,"completion_tokens": 46,"total_tokens": 1163,"prompt_tokens_details": { "cached_tokens": 0 },"completion_tokens_details": { "reasoning_tokens": 0 }},"service_tier": "default","system_fingerprint": "fp_fc9f1d7035"}

How it maps to OCRRouter output

output[].content[] where type is output_text
Text parts joined into one string (direct path)
choices[0].message.content
The text, string or array of text parts joined (gateway path)
<!-- page:N --> markers
Text split into pages[]; a stray code fence is removed; no markers means one page; extra pages are merged into the last
Empty text
Request fails with "Provider returned no text"
Layout and confidence
None: no bbox or confidence from this model

The unified output is described in Response format.

Example request

curl https://api.ocrrouter.ai/v1/ocr \
  -H "Authorization: Bearer $OCRROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt",
    "file_url": "https://example.com/invoice.pdf",
    "format": "json"
  }'

Sources

Vendor documentation read on 2026-11-19.