---
title: How to query OCR models
description: Learn how to interact with powerful OCR models using Scaleway Generative APIs.
tags: generative-apis ai-data ocr-models chat-completions-api
dates:
  validation: 2025-10-13
  posted: 2026-10-13
---
import Requirements from '@macros/iam/requirements.mdx'

The Scaleway Generative APIs service allows users to interact with powerful OCR (Optical Character Recognition) models hosted on the platform.

<Message type="note">
  - OCR models are designed specifically to detect and extract text from images. They focus on identifying characters, words, and text layout within an image. 
  - They are different from [vision models](/generative-apis/how-to/query-vision-models/), which are designed to analyze visual content, such as objects, scenes, and activities. 
</Message>

There are several ways to interact with OCR models:

- **Scaleway console playground**: The Scaleway [console](https://console.scaleway.com) provides a complete [playground](/generative-apis/quickstart/#interacting-with-generative-apis-via-the-playground) for Generative APIs. This visual interface allows you to test models, adapt query parameters, and observe how these changes affect the output in real-time.
- **[Chat Completions API](https://www.scaleway.com/en/developers/api/generative-apis/chat-completions)**: Use the Chat Completions API to query OCR models programmatically.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/glossary/#owner) status or [IAM permissions](/iam/concepts/glossary/#permission) allowing you to perform actions in the intended Organization
- A valid [API key](/iam/credentials/create-api-keys/) for API authentication
- Python 3.7+ installed on your system

## Access the playground

Scaleway provides a web playground for OCR models hosted on Generative APIs.

1. In the [Scaleway console](https://console.scaleway.com/) side menu, go to **AI** >  **Generative APIs**. The list of models you can query appears. 
2. Select the **Serverless** toggle button.
3. Click the name of the OCR model you want to try. Alternatively, click **Try** next to the name of the model.

The web playground opens.

## Use the playground

1. Upload a `.pdf` file to the prompt area at the bottom of the page, or click **Analyze sample document**. The model starts detecting your document and rendering text. 
2. Scroll down the rendered text to find an estimation of the number of input/output tokens, and the total amount of consumed tokens for this task. 
3. Click **Use** to see the code snippets configured according to your settings in the playground. 


## Query OCR models via the API

You can query OCR models programmatically using your favorite tools or languages.

OCR models take both text and images as inputs.

In the example that follows, we will use the OpenAI Python client.

<Message type="tip">
  Unlike traditional language models, OCR models take a single file as input. See the `python` example below to understand the expected requested format.
</Message>

### Install the OpenAI SDK

Install the OpenAI SDK using pip:

```bash
pip install openai
```

### Initialize the client

Initialize the OpenAI client with your base URL and API key, and define the file that you want to analyze. For the example, we will use this file: https://genapi-documentation-assets.s3.fr-par.scw.cloud/scaleway-impact-report-3-pages.pdf.


```python
from openai import OpenAI
import base64
import os
import urllib.request

# Define the FILE that the OCR model will analyze. Here we use a public Scaleway document for the example
FILE = "https://genapi-documentation-assets.s3.fr-par.scw.cloud/scaleway-impact-report-3-pages.pdf"

# Initialize the client with your base URL and API key
client = OpenAI(
    base_url = "https://api.scaleway.ai/999d23ea-7afa-485f-9d6c-27db078f1527/v1",
    api_key = os.getenv"<SCW_SECRET_KEY>" # Replace <SCW_SECRET_KEY> with your IAM API key
)

with urllib.request.urlopen(FILE) as response:
    encoded_file = base64.b64encode(response.read()).decode("utf-8")
```

### Generate a chat completion

You can now create a chat completion:

```python
response = client.chat.completions.create(
  model="lightonocr-3-0.8b",
  messages=[
    {
      "role": "user",
      "content": [{
        "type": "file",
        "file": {
            "file_data": f"data:application/pdf;base64,{encoded_file}"
        }
      }
      ]
    }
  ],
  stream=False,
)

if response.choices and response.choices[0].message.content:
    print(response.choices[0].message.content)
```