How to query OCR models

Reviewed on October 13, 2025

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

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, which are designed to analyze visual content, such as objects, scenes, and activities.

There are several ways to interact with OCR models:

Scaleway console playground: The Scaleway console (External link) provides a complete 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 (External link): Use the Chat Completions API to query OCR models programmatically.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console (External link)
Owner status or IAM permissions allowing you to perform actions in the intended Organization
A valid API key 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.

In the Scaleway console (External link) side menu, go to AI > Generative APIs. The list of models you can query appears.
Select the Serverless toggle button.
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

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.
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.
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.

Tip

Unlike traditional language models, OCR models take a single file as input. See the python example below to understand the expected requested format.

Install the OpenAI SDK

Install the OpenAI SDK using pip:

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 (PDF).

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:

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)