> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/ocr.md).

# OCR

## Create Ocr

> Extracts text from files using Mistral Document AI pipeline

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.8.0"},"tags":[{"name":"OCR"}],"servers":[{"url":"https://albert.api.etalab.gouv.fr"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateOCRBody":{"properties":{"bbox_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the bounding boxes. 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."},"document":{"anyOf":[{"$ref":"#/components/schemas/DocumentURLChunk"},{"$ref":"#/components/schemas/ImageURLChunk"}],"title":"Document","description":"Document to run OCR on."},"document_annotation_format":{"anyOf":[{"$ref":"#/components/schemas/ResponseFormat"},{"type":"null"}],"description":"Specify the format that the model must output for the document. 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."},"document_annotation_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation Prompt","description":"Optional prompt to guide the model in extracting structured output from the entire document. A document_annotation_format must be provided."},"extract_footer":{"type":"boolean","title":"Extract Footer","description":"Whether to extract the footer of the document.","default":false},"extract_header":{"type":"boolean","title":"Extract Header","description":"Whether to extract the header of the document.","default":false},"image_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Limit","description":"Max images to extract"},"image_min_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Min Size","description":"Minimum height and width of image to extract"},"include_image_base64":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Image Base64","description":"Include image URLs in response"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model to use for the OCR, call `/v1/models` endpoint to get the list of available models, only `image-to-text` model type is supported."},"pages":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Pages","description":"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":{"anyOf":[{"type":"string","enum":["markdown","html"]},{"type":"null"}],"title":"Table Format","description":"Format for table extraction: 'markdown' (default) or 'html'."}},"additionalProperties":true,"type":"object","required":["document"],"title":"CreateOCRBody"},"ResponseFormat":{"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"],"title":"Type","description":"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.","default":"text"},"json_schema":{"anyOf":[{"$ref":"#/components/schemas/JsonSchema"},{"type":"null"}],"description":"The JSON schema definition. Required when type is 'json_schema'."}},"additionalProperties":true,"type":"object","title":"ResponseFormat"},"JsonSchema":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the JSON schema."},"schema":{"additionalProperties":true,"type":"object","title":"Schema","description":"The JSON schema definition."},"strict":{"type":"boolean","title":"Strict","description":"Whether to use strict mode.","default":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the schema."}},"additionalProperties":true,"type":"object","required":["name","schema"],"title":"JsonSchema"},"DocumentURLChunk":{"properties":{"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name","description":"The filename of the document."},"document_url":{"type":"string","title":"Document Url","description":"The URL of the document."},"type":{"type":"string","const":"document_url","title":"Type","description":"The type of the document.","default":"document_url"}},"additionalProperties":true,"type":"object","required":["document_url"],"title":"DocumentURLChunk"},"ImageURLChunk":{"properties":{"image_url":{"anyOf":[{"$ref":"#/components/schemas/api__infrastructure__fastapi__schemas__ocr__ImageURL"},{"type":"string"}],"title":"Image Url","description":"The URL of the image to OCR."},"type":{"type":"string","const":"image_url","title":"Type","description":"The type of the image.","default":"image_url"}},"additionalProperties":true,"type":"object","required":["image_url"],"title":"ImageURLChunk"},"api__infrastructure__fastapi__schemas__ocr__ImageURL":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"The detail of the image."},"url":{"type":"string","title":"Url","description":"The URL of the image."}},"additionalProperties":true,"type":"object","required":["url"],"title":"ImageURL"},"OCRResponse":{"properties":{"document_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Annotation","description":"Formatted response in the request_format if provided in json str"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"The ID of the OCR request."},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"The model used to generate the OCR."},"pages":{"items":{"$ref":"#/components/schemas/OCRPageObject"},"type":"array","title":"Pages","description":"List of OCR info for pages."},"usage":{"anyOf":[{"$ref":"#/components/schemas/api__domain__usage__entities__Usage"},{"type":"null"}],"description":"Usage information for the request."},"usage_info":{"anyOf":[{"$ref":"#/components/schemas/OCRUsage"},{"type":"null"}],"description":"Usage information for the request."}},"additionalProperties":true,"type":"object","required":["pages"],"title":"OCRResponse"},"OCRPageObject":{"properties":{"dimensions":{"anyOf":[{"$ref":"#/components/schemas/OCRPageDimensions"},{"type":"null"}],"description":"The dimensions of the PDF Page's screenshot image"},"footer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Footer","description":"The footer of the page, returned when extract_footer is enabled"},"header":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header","description":"The header of the page, returned when extract_header is enabled"},"hyperlinks":{"items":{"type":"string"},"type":"array","title":"Hyperlinks","description":"The hyperlinks extracted from the page.","default":[]},"images":{"items":{"$ref":"#/components/schemas/OCRImageObject"},"type":"array","title":"Images","description":"List of all extracted images in the page."},"index":{"type":"integer","title":"Index","description":"The page index in a pdf document starting from 0"},"markdown":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown","description":"The markdown string response of the page"},"tables":{"items":{"$ref":"#/components/schemas/OCRTableObject"},"type":"array","title":"Tables","description":"The tables extracted from the page, in the requested table_format.","default":[]}},"additionalProperties":true,"type":"object","required":["images","index"],"title":"OCRPageObject"},"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi","description":"Dots per inch of the page-image"},"height":{"type":"integer","title":"Height","description":"Height of the image in pixels"},"width":{"type":"integer","title":"Width","description":"Width of the image in pixels"}},"additionalProperties":true,"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"},"OCRImageObject":{"properties":{"bottom_right_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right X","description":"X coordinate of bottom-right corner of the extracted image"},"bottom_right_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bottom Right Y","description":"Y coordinate of bottom-right corner of the extracted image"},"id":{"type":"string","title":"Id","description":"Image ID for extracted image in a page"},"image_annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Annotation","description":"Annotation of the extracted image in json str"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64 string of the extracted image"},"top_left_x":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left X","description":"X coordinate of top-left corner of the extracted image"},"top_left_y":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Top Left Y","description":"Y coordinate of top-left corner of the extracted image"}},"additionalProperties":true,"type":"object","required":["id"],"title":"OCRImageObject"},"OCRTableObject":{"properties":{"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"The content of the extracted table, in the requested table format"},"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"The format of the extracted table: 'markdown' or 'html'"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Table ID for the extracted table in a page"}},"additionalProperties":true,"type":"object","title":"OCRTableObject"},"api__domain__usage__entities__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","default":0},"cost":{"type":"number","title":"Cost","default":0},"impacts":{"$ref":"#/components/schemas/api__domain__usage__entities__EnvironmentalImpacts","default":{"kWh":0,"kgCO2eq":0}}},"additionalProperties":true,"type":"object","title":"Usage"},"api__domain__usage__entities__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"OCRUsage":{"properties":{"doc_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Doc Size Bytes","description":"Document size in bytes"},"pages_processed":{"type":"integer","title":"Pages Processed","description":"Number of pages processed"}},"additionalProperties":true,"type":"object","required":["pages_processed"],"title":"OCRUsage"},"api__infrastructure__fastapi__documentation__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"detail":{"type":"string","title":"Detail"},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers"}},"type":"object","required":["status_code","detail"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/ocr":{"post":{"tags":["OCR"],"summary":"Create Ocr","description":"Extracts text from files using Mistral Document AI pipeline","operationId":"create_ocr_v1_ocr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOCRBody","description":"The OCR creation request."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OCRResponse"}}}},"400":{"description":"Insufficient budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"401":{"description":"Invalid authentication scheme.<br>Invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"403":{"description":"Your account has expired. Please contact support to renew your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"404":{"description":"Model {name} not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"422":{"description":"Model has wrong type. Expected: {expected_type}. Actual: {actual_type}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"429":{"description":"Token/request limit per minute/day exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__infrastructure__fastapi__documentation__HTTPExceptionModel"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/ocr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.