---
title: "Perform OCR"
method: POST
path: "/v1/ocr"
tags: ["OCR"]
---

# Perform OCR

`POST /v1/ocr`

Extracts text and content from documents or images using optical character recognition.
Supports PDF URLs, base64-encoded documents, and image URLs.

## Request body

- OCRRequest
  - `model` string, required — Model in provider/model format
  - `id` string — Optional unique identifier for the request
  - `document` union, required
    - object
      - `type` 'document_url', required — Type of document input: - `document_url`: A PDF URL or base64 data URL - `image_url`: An image URL
      - `document_url` string, required — URL or base64 data URL of the document (required when type is document_url)
      - `image_url` string — URL of the image to process (required when type is image_url)
    - object
      - `type` 'image_url', required — Type of document input: - `document_url`: A PDF URL or base64 data URL - `image_url`: An image URL
      - `document_url` string — URL or base64 data URL of the document (required when type is document_url)
      - `image_url` string, required — URL of the image to process (required when type is image_url)
  - `fallbacks` string[] — Fallback models in provider/model format
  - `include_image_base64` boolean — Whether to include base64-encoded images in the response
  - `pages` integer[] — Specific page indices to process (0-based)
  - `image_limit` integer — Maximum number of images to extract per page
  - `image_min_size` integer — Minimum image size in pixels to extract
  - `table_format` string — Format for extracted tables (e.g., "markdown", "html")
  - `extract_header` boolean — Whether to extract page headers
  - `extract_footer` boolean — Whether to extract page footers
  - `confidence_scores_granularity` 'page' | 'block' | 'word' | 'document' — Granularity of confidence scores to include in the response
  - `bbox_annotation_format` union — Format for bounding box annotations. Supports text, json_object, and json_schema modes.
    - object
      - `type` 'text' | 'json_object', required — The format type
      - `json_schema` object — JSON schema definition (required when type is json_schema)
        - `schema` object — The JSON schema
        - `name` string — Name of the schema
        - `strict` boolean — Whether to enforce strict validation
    - object
      - `type` 'json_schema', required — The format type
      - `json_schema` object, required — JSON schema definition (required when type is json_schema)
        - `schema` object — The JSON schema
        - `name` string — Name of the schema
        - `strict` boolean — Whether to enforce strict validation
  - `document_annotation_format` union — Format for document-level annotations. Supports text, json_object, and json_schema modes.
    - object
      - `type` 'text' | 'json_object', required — The format type
      - `json_schema` object — JSON schema definition (required when type is json_schema)
        - `schema` object — The JSON schema
        - `name` string — Name of the schema
        - `strict` boolean — Whether to enforce strict validation
    - object
      - `type` 'json_schema', required — The format type
      - `json_schema` object, required — JSON schema definition (required when type is json_schema)
        - `schema` object — The JSON schema
        - `name` string — Name of the schema
        - `strict` boolean — Whether to enforce strict validation
  - `document_annotation_prompt` string — Custom prompt for document annotation

## Response `200`

Successful response

- OCRResponse
  - `model` string, required — Model used to perform OCR
  - `pages` OCRPage[], required — Processed pages with extracted content
    - `index` integer, required — Zero-based page index
    - `markdown` string, required — Extracted text content in Markdown format
    - `images` OCRPageImage[] — Images extracted from this page
      - `id` string, required — Unique identifier for the image within the page
      - `top_left_x` number, required — X coordinate of the top-left corner of the image bounding box
      - `top_left_y` number, required — Y coordinate of the top-left corner of the image bounding box
      - `bottom_right_x` number, required — X coordinate of the bottom-right corner of the image bounding box
      - `bottom_right_y` number, required — Y coordinate of the bottom-right corner of the image bounding box
      - `image_base64` string — Base64-encoded image data (present when include_image_base64 is true)
    - `dimensions` OCRPageDimensions
      - `dpi` integer, required — Dots per inch of the page
      - `height` integer, required — Page height in pixels
      - `width` integer, required — Page width in pixels
    - `tables` object[], nullable — Tables extracted from this page (present when table_format is set)
    - `header` string, nullable — Header content extracted from this page (present when extract_header is true)
    - `footer` string, nullable — Footer content extracted from this page (present when extract_footer is true)
    - `confidence_scores` object, nullable — Confidence scores for this page (present when confidence_scores_granularity is set)
      - `average_page_confidence_score` number — Average confidence score for the page
      - `minimum_page_confidence_score` number — Minimum confidence score for the page
      - `word_confidence_scores` number[] — Per-word confidence scores
  - `usage_info` OCRUsageInfo
    - `pages_processed` integer, required — Number of pages processed
    - `doc_size_bytes` integer, required — Size of the processed document in bytes
  - `document_annotation` string — Document-level annotation if requested
  - `extra_fields` BifrostResponseExtraFields — Additional fields included in responses
    - `request_type` string — Type of request that was made
    - `provider` 'openai' | 'azure' | 'anthropic' | 'bedrock' | 'cohere' | 'vertex' | 'vllm' | 'mistral' | 'ollama' | 'groq' | 'sgl' | 'parasail' | 'perplexity' | 'replicate' | 'cerebras' | 'deepseek' | 'gemini' | 'openrouter' | 'elevenlabs' | 'huggingface' | 'nebius' | 'xai' | 'runway' | 'fireworks' — AI model provider identifier
    - `model_requested` string — The model that was requested
    - `model_deployment` string — The actual model deployment used
    - `latency` integer — Request latency in milliseconds
    - `chunk_index` integer — Index of the chunk for streaming responses
    - `raw_request` object — Raw request if enabled
    - `raw_response` object — Raw response if enabled
    - `cache_debug` BifrostCacheDebug
      - `cache_hit` boolean
      - `cache_id` string
      - `hit_type` string
      - `requested_provider` string
      - `requested_model` string
      - `provider_used` string
      - `model_used` string
      - `input_tokens` integer
      - `threshold` number
      - `similarity` number

## Other responses

- `400` — Bad request
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/revisions/f8cab88f64ea/schema)