Skip to main content

​
Overview

This guide walks you through creating a dataset and populating it with images using the Orq API. You’ll learn how to:
  • Initialize the Orq client
  • Create a new dataset
  • Convert images to base64 format
  • Add images with prompts to your dataset

​
Prerequisites

  • An Orq API key (to create a new key, see API keys)
  • Images in a supported format (JPEG, PNG, GIF, WEBP)

​
Installation

1

Install the SDK

pip install orq-ai-sdk
2

Initialize the Client

# Set your API key as an environment variable
export ORQ_API_KEY="your_api_key"
3

Create a Dataset

Start by creating a new Dataset to organize your images, we’ll be using the Create Dataset Endpoint.
curl -X POST https://api.orq.ai/v2/datasets \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Image Analysis Dataset",
    "path": "Default"
  }'
Response:
{
  "id": "01K99J7RF0W7PSV4XTJM5XZR1J",
  "display_name": "Image Analysis Dataset",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
4

Convert Images to Base64

Images must be encoded as base64 data URLs before adding to the dataset:
# Convert a single image to base64 using bash
IMAGE_PATH="/path/to/image.jpg"
IMAGE_DATA=$(base64 < "$IMAGE_PATH" | tr -d '\n')
MIME_TYPE="image/jpeg"

# Create the data URL
DATA_URL="data:${MIME_TYPE};base64,${IMAGE_DATA}"
echo "$DATA_URL"
5

Add your images to the Dataset

We’ll be using the add Datapoint to a Dataset endpoint.
# Convert image to base64 and send to API
DATASET_ID="01K99J7RF0W7PSV4XTJM5XZR1J"
IMAGE_PATH="/path/to/image.jpg"
IMAGE_DATA=$(base64 < "$IMAGE_PATH" | tr -d '\n')

curl -X POST "https://api.orq.ai/v2/datasets/$DATASET_ID/datapoints" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Describe what you see in this image"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,'$IMAGE_DATA'",
              "detail": "auto"
            }
          }
        ]
      }
    ]
  }'

​
See the Full Example

Here’s a complete working example with error handling:
from orq_ai_sdk import Orq
import base64
import glob
import os

# Initialize client
orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

# Helper function
def image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        encoded = base64.b64encode(image_file.read()).decode('utf-8')

    extension = image_path.lower().split('.')[-1]
    mime_types = {
        'png': 'image/png',
        'gif': 'image/gif',
        'webp': 'image/webp',
        'jpg': 'image/jpeg',
        'jpeg': 'image/jpeg'
    }
    mime_type = mime_types.get(extension, 'image/jpeg')
    return f"data:{mime_type};base64,{encoded}"

# Create dataset
dataset = orq.datasets.create(
    request={
        "display_name": "My Image Dataset",
        "path": "Default",
    }
)
dataset_id = dataset.id
print(f" Dataset created: {dataset_id}")

# Process images
image_extensions = ['jpg', 'jpeg', 'png', 'gif', 'webp']
images_folder = "/path/to/images"

all_images = []
for ext in image_extensions:
    all_images.extend(glob.glob(os.path.join(images_folder, f'*.{ext}')))
    all_images.extend(glob.glob(os.path.join(images_folder, f'*.{ext.upper()}')))

successful = 0
failed = 0

for idx, image_path in enumerate(all_images, 1):
    try:
        image_data = image_to_base64(image_path)

        orq.datasets.create_datapoint(
            dataset_id=dataset_id,
            request_body=[{
                "messages": [{
                    "role": "user",
                    "content": [
                        {
                            "type": "text",
                            "text": "Describe this image"
                        },
                        {
                            "type": "image_url",
                            "image_url": {
                                "url": image_data,
                                "detail": "auto"
                            }
                        }
                    ]
                }]
            }]
        )

        successful += 1
        print(f"[{idx}/{len(all_images)}]  {os.path.basename(image_path)}")

    except Exception as e:
        failed += 1
        print(f"[{idx}/{len(all_images)}]  {os.path.basename(image_path)}: {str(e)}")

print(f"\n{'='*50}")
print(f" Complete! Added {successful}/{len(all_images)} images")
print(f"Dataset ID: {dataset_id}")

​
Image Format Details

​
Supported Formats

FormatMIME TypeExtension
JPEGimage/jpeg.jpg, .jpeg
PNGimage/png.png
GIFimage/gif.gif
WebPimage/webp.webp

​
Detail Parameter

The detail parameter controls how the image is processed:
  • auto (recommended): Automatically optimizes based on image size
  • low: Faster processing, lower token usage
  • high: More detailed analysis, higher token usage

​
Error Handling

Common issues and solutions:
ErrorCauseSolution
Invalid API keyAuthentication failedCheck your API key in console.orq.ai/settings/api-keys
File not foundImage path is incorrectVerify the image path and file permissions
Unsupported formatImage format not supportedConvert to JPEG, PNG, GIF, or WebP
Payload too largeImage file is too largeCompress or resize images before upload