Sign In Get Started

Quick Start

Get up and running with the Pictograph SDK in minutes.

This guide walks you through authenticating with the API and performing common operations like listing datasets, downloading annotations, and creating exports.

Prerequisites

Before you begin, make sure you have:

  • Python 3.8 or higher installed on your system
  • A Pictograph account with at least one dataset
  • pip package manager (included with Python)

1. Install the SDK

Bash 
pip install pictograph

2. Get Your API Key

  1. Sign in to app.pictograph.io
  2. Go to Settings → API Keys
  3. Click Generate New Key
  4. Copy your API key (starts with pk_live_)
Important: Your API key is only shown once. Store it securely and never commit it to version control.

2. Initialize the Client

import os
from pictograph import Client
from dotenv import load_dotenv

# Fetch .env environment variables
load_dotenv()

# Recommended: Use environment variable
client = Client(api_key=os.environ.get("PICTOGRAPH_API_KEY"))
import requests

API_KEY = "{{API_KEY}}"
BASE_URL = "https://api.pictograph.io/api/v1/developer"
HEADERS = {"X-API-Key": API_KEY}
const API_KEY = "{{API_KEY}}";
const BASE_URL = "https://api.pictograph.io/api/v1/developer";

async function apiRequest(endpoint, options = {}) {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      "X-API-Key": API_KEY,
      ...options.headers
    }
  });
  return response.json();
}
# Set your API key as an environment variable
export PICTOGRAPH_API_KEY="{{API_KEY}}"

# Use in requests
curl https://api.pictograph.io/api/v1/developer/datasets/ \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

3. List Your Datasets

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
datasets = client.datasets.list()

for dataset in datasets:
    print(f"{dataset['name']}: {dataset['image_count']} images")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/datasets/",
    headers={"X-API-Key": "{{API_KEY}}"}
)
datasets = response.json()

for dataset in datasets:
    print(f"{dataset['name']}: {dataset['image_count']} images")
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/datasets/",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const datasets = await response.json();

datasets.forEach(dataset => {
  console.log(`${dataset.name}: ${dataset.image_count} images`);
});
curl https://api.pictograph.io/api/v1/developer/datasets/ \
  -H "X-API-Key: {{API_KEY}}"

4. Download a Dataset

Download images and annotations to a local directory:

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.datasets.download(
    "{{DATASET}}",
    output_dir="./data",
    mode="full",
    max_workers=20
)
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET}}/download",
    headers={"X-API-Key": "{{API_KEY}}"},
    params={"mode": "full"}
)
data = response.json()

for img in data["images"]:
    img_resp = requests.get(img["download_url"])
    with open(f"./{img['filename']}", "wb") as f:
        f.write(img_resp.content)
curl "https://api.pictograph.io/api/v1/developer/datasets/by-name/{{DATASET}}/download?mode=full" \
  -H "X-API-Key: {{API_KEY}}"

5. Work with Annotations

Get annotations for a specific image:

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
annotations = client.annotations.get("{{IMAGE_ID}}")

for ann in annotations:
    print(f"{ann['name']}: {ann['type']}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
data = response.json()

for ann in data["annotations"]:
    print(f"Class: {ann['name']}, Type: {ann['type']}")
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/annotations/{{IMAGE_ID}}",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const { annotations } = await response.json();

annotations.forEach(ann => {
  console.log(`Class: ${ann.name}, Type: ${ann.type}`);
});

6. Create an Export

Create a downloadable ZIP archive of your dataset:

from pictograph import Client

client = Client(api_key="{{API_KEY}}")

export = client.exports.create(
    dataset_name="{{DATASET}}",
    name="Training Export v1",
    wait=True
)

path = client.exports.download("{{DATASET}}", "Training Export v1")
import requests

response = requests.post(
    "https://api.pictograph.io/api/v1/developer/exports/",
    headers={"X-API-Key": "{{API_KEY}}", "Content-Type": "application/json"},
    json={"dataset_name": "{{DATASET}}", "name": "Training Export v1"}
)
export_id = response.json()["id"]
curl -X POST https://api.pictograph.io/api/v1/developer/exports/ \
  -H "X-API-Key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{"dataset_name": "{{DATASET}}", "name": "Training Export v1"}'

Troubleshooting

If you encounter errors, see the Error Handling guide for detailed troubleshooting steps, HTTP status codes, and the complete error reference.

Tip: The SDK automatically handles rate limiting and retries for you. Use the SDK for the best experience.

Next Steps

Copied to clipboard