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

# Ocr

`POST /v1/ocr`

Extracts text from files using OCR.

## Request body

- CreateOCR
  - `bbox_annotation_format` ResponseFormat
    - `type` 'text' | 'json_object' | 'json_schema' — Specify the format that the model must output. By default it will use `{ "type": "text" }`. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ "type": "json_schema" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.
    - `json_schema` JsonSchema
      - `name` string, required — The name of the JSON schema.
      - `schema` object, required — The JSON schema definition.
      - `strict` boolean — Whether to use strict mode.
      - `description` string, nullable — Optional description of the schema.
  - `document` union, required — Document to run OCR on.
    - DocumentURLChunk
      - `document_name` string, nullable — The filename of the document.
      - `document_url` string, required — The URL of the document.
      - `type` 'document_url' — The type of the document.
    - ImageURLChunk
      - `image_url` union, required — The URL of the image to OCR.
        - ImageURL
          - `detail` string, nullable — The detail of the image.
          - `url` string, required — The URL of the image.
        - string
      - `type` 'image_url' — The type of the image.
  - `document_annotation_format` ResponseFormat
    - `type` 'text' | 'json_object' | 'json_schema' — Specify the format that the model must output. By default it will use `{ "type": "text" }`. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ "type": "json_schema" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.
    - `json_schema` JsonSchema
      - `name` string, required — The name of the JSON schema.
      - `schema` object, required — The JSON schema definition.
      - `strict` boolean — Whether to use strict mode.
      - `description` string, nullable — Optional description of the schema.
  - `document_annotation_prompt` string, nullable — Optional prompt to guide the model in extracting structured output from the entire document. A document_annotation_format must be provided.
  - `extract_footer` boolean — Whether to extract the footer of the document.
  - `extract_header` boolean — Whether to extract the header of the document.
  - `image_limit` integer, nullable — Max images to extract
  - `image_min_size` integer, nullable — Minimum height and width of image to extract
  - `include_image_base64` boolean, nullable — Include image URLs in response
  - `model` string, nullable — The model to use for the OCR.
  - `pages` integer[], nullable — Specific pages to process. Accepts a list of integers or a string of comma-separated numbers and ranges (e.g. '0,1,2' or '0-5' or '0,2-4'). Page numbers start from 0.
  - `table_format` 'markdown' | 'html', nullable — Format for table extraction: 'markdown' (default) or 'html'.

## Response `200`

Successful Response

- OCR
  - `pages` OCRPageObject[], required
    - `index` integer, required
    - `markdown` string, required
    - `images` OCRImageObject[], required
      - `id` string, required
      - `top_left_x` integer, nullable, required
      - `top_left_y` integer, nullable, required
      - `bottom_right_x` integer, nullable, required
      - `bottom_right_y` integer, nullable, required
      - `image_base64` union
        - string, nullable
        - Unset
      - `image_annotation` union
        - string, nullable
        - Unset
    - `dimensions` NullableOCRPageDimensions, required
      - `dpi` integer, required
      - `height` integer, required
      - `width` integer, required
    - `tables` OCRTableObject[], nullable
      - `id` string, required
      - `content` string, required
      - `format` 'markdown' | 'html', required
    - `hyperlinks` string[], nullable
    - `header` union
      - string, nullable
      - Unset
    - `footer` union
      - string, nullable
      - Unset
  - `model` string, required
  - `usage_info` OCRUsageInfo, required
    - `pages_processed` integer, required
    - `doc_size_bytes` union
      - integer, nullable
      - Unset
  - `document_annotation` union
    - string, nullable
    - Unset
  - `id` string, required — The ID of the OCR request.
  - `usage` ApiSchemasUsageUsage
    - `prompt_tokens` integer — Number of prompt tokens (e.g. input tokens).
    - `completion_tokens` integer — Number of completion tokens (e.g. output tokens).
    - `total_tokens` integer — Total number of tokens (e.g. input and output tokens).
    - `cost` number — Total cost of the request.
    - `carbon` CarbonFootprintUsage
      - `kWh` CarbonFootprintUsageKWh
        - `min` number — Minimum carbon footprint in kWh.
        - `max` number — Maximum carbon footprint in kWh.
      - `kgCO2eq` CarbonFootprintUsageKgCO2eq
        - `min` number — Minimum carbon footprint in kgCO2eq (global warming potential).
        - `max` number — Maximum carbon footprint in kgCO2eq (global warming potential).
    - `impacts` ApiSchemasUsageEnvironmentalImpacts
      - `kWh` number — Carbon footprint in kWh.
      - `kgCO2eq` number — Carbon footprint in kgCO2eq (global warming potential).
    - `requests` integer — Number of model requests.

## Other responses

- `404` — Model not found.
- `422` — Wrong model type.
- `503` — Model is too busy, please try again later.

---

[API](https://skmtc.net/betagouv/apis/opengatellm.md) · [All operations](https://skmtc.net/betagouv/apis/opengatellm/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/betagouv/opengatellm/versions/f2624a610e5a/schema)