> 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

## Ocr

> Extracts text from files using OCR.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateOCR":{"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."},"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":"CreateOCR"},"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/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"},"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"},"OCR":{"properties":{"pages":{"items":{"$ref":"#/components/schemas/OCRPageObject"},"type":"array","title":"Pages"},"model":{"type":"string","title":"Model"},"usage_info":{"$ref":"#/components/schemas/OCRUsageInfo"},"document_annotation":{"$ref":"#/components/schemas/OptionalNullable_str_","default":"~?~unset~?~sentinel~?~"},"id":{"type":"string","title":"Id","description":"The ID of the OCR request."},"usage":{"anyOf":[{"$ref":"#/components/schemas/api__schemas__usage__Usage"},{"type":"null"}],"description":"Usage information for the request."}},"type":"object","required":["pages","model","usage_info","id"],"title":"OCR"},"OCRPageObject":{"properties":{"index":{"type":"integer","title":"Index"},"markdown":{"type":"string","title":"Markdown"},"images":{"items":{"$ref":"#/components/schemas/OCRImageObject"},"type":"array","title":"Images"},"dimensions":{"$ref":"#/components/schemas/Nullable_OCRPageDimensions_"},"tables":{"anyOf":[{"items":{"$ref":"#/components/schemas/OCRTableObject"},"type":"array"},{"type":"null"}],"title":"Tables"},"hyperlinks":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Hyperlinks"},"header":{"$ref":"#/components/schemas/OptionalNullable_str_","default":"~?~unset~?~sentinel~?~"},"footer":{"$ref":"#/components/schemas/OptionalNullable_str_","default":"~?~unset~?~sentinel~?~"}},"type":"object","required":["index","markdown","images","dimensions"],"title":"OCRPageObject"},"OCRImageObject":{"properties":{"id":{"type":"string","title":"Id"},"top_left_x":{"$ref":"#/components/schemas/Nullable_int_"},"top_left_y":{"$ref":"#/components/schemas/Nullable_int_"},"bottom_right_x":{"$ref":"#/components/schemas/Nullable_int_"},"bottom_right_y":{"$ref":"#/components/schemas/Nullable_int_"},"image_base64":{"$ref":"#/components/schemas/OptionalNullable_str_","default":"~?~unset~?~sentinel~?~"},"image_annotation":{"$ref":"#/components/schemas/OptionalNullable_str_","default":"~?~unset~?~sentinel~?~"}},"type":"object","required":["id","top_left_x","top_left_y","bottom_right_x","bottom_right_y"],"title":"OCRImageObject"},"Nullable_int_":{"anyOf":[{"type":"integer"},{"type":"null"}]},"OptionalNullable_str_":{"anyOf":[{"$ref":"#/components/schemas/Nullable_str_"},{"$ref":"#/components/schemas/Unset"},{"type":"null"}]},"Nullable_str_":{"anyOf":[{"type":"string"},{"type":"null"}]},"Unset":{"properties":{},"type":"object","title":"Unset"},"Nullable_OCRPageDimensions_":{"anyOf":[{"$ref":"#/components/schemas/OCRPageDimensions"},{"type":"null"}]},"OCRPageDimensions":{"properties":{"dpi":{"type":"integer","title":"Dpi"},"height":{"type":"integer","title":"Height"},"width":{"type":"integer","title":"Width"}},"type":"object","required":["dpi","height","width"],"title":"OCRPageDimensions"},"OCRTableObject":{"properties":{"id":{"type":"string","title":"Id"},"content":{"type":"string","title":"Content"},"format":{"type":"string","enum":["markdown","html"],"title":"Format"}},"type":"object","required":["id","content","format"],"title":"OCRTableObject"},"OCRUsageInfo":{"properties":{"pages_processed":{"type":"integer","title":"Pages Processed"},"doc_size_bytes":{"$ref":"#/components/schemas/OptionalNullable_int_","default":"~?~unset~?~sentinel~?~"}},"type":"object","required":["pages_processed"],"title":"OCRUsageInfo"},"OptionalNullable_int_":{"anyOf":[{"$ref":"#/components/schemas/Nullable_int_"},{"$ref":"#/components/schemas/Unset"},{"type":"null"}]},"api__schemas__usage__Usage":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","description":"Number of prompt tokens (e.g. input tokens).","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","description":"Number of completion tokens (e.g. output tokens).","default":0},"total_tokens":{"type":"integer","title":"Total Tokens","description":"Total number of tokens (e.g. input and output tokens).","default":0},"cost":{"type":"number","title":"Cost","description":"Total cost of the request.","default":0},"carbon":{"$ref":"#/components/schemas/CarbonFootprintUsage","deprecated":true},"impacts":{"$ref":"#/components/schemas/api__schemas__usage__EnvironmentalImpacts"},"requests":{"type":"integer","title":"Requests","description":"Number of model requests.","default":0}},"additionalProperties":true,"type":"object","title":"Usage"},"CarbonFootprintUsage":{"properties":{"kWh":{"$ref":"#/components/schemas/CarbonFootprintUsageKWh","deprecated":true},"kgCO2eq":{"$ref":"#/components/schemas/CarbonFootprintUsageKgCO2eq","deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsage"},"CarbonFootprintUsageKWh":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kWh.","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kWh.","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKWh"},"CarbonFootprintUsageKgCO2eq":{"properties":{"min":{"type":"number","title":"Min","description":"Minimum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true},"max":{"type":"number","title":"Max","description":"Maximum carbon footprint in kgCO2eq (global warming potential).","default":0,"deprecated":true}},"additionalProperties":true,"type":"object","title":"CarbonFootprintUsageKgCO2eq"},"api__schemas__usage__EnvironmentalImpacts":{"properties":{"kWh":{"type":"number","title":"Kwh","description":"Carbon footprint in kWh.","default":0},"kgCO2eq":{"type":"number","title":"Kgco2Eq","description":"Carbon footprint in kgCO2eq (global warming potential).","default":0}},"additionalProperties":true,"type":"object","title":"EnvironmentalImpacts"},"api__schemas__exception__HTTPExceptionModel":{"properties":{"status_code":{"type":"integer","maximum":599,"minimum":100,"title":"Status Code","description":"HTTP status code to send to the client."},"detail":{"title":"Detail","description":"Any data to be sent to the client in the `detail` key of the JSON response."},"headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Headers","description":"Any headers to send to the client in the response."}},"type":"object","required":["status_code","detail","headers"],"title":"HTTPExceptionModel"}}},"paths":{"/v1/ocr":{"post":{"tags":["OCR"],"summary":"Ocr","description":"Extracts text from files using OCR.","operationId":"ocr_v1_ocr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOCR"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OCR"}}}},"404":{"description":"Model not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__HTTPExceptionModel"}}}},"422":{"description":"Wrong model type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__HTTPExceptionModel"}}}},"503":{"description":"Model is too busy, please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__schemas__exception__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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.