Sign in Get started

Quick start

Install the Pictograph SDK, get an API key, and run your first end-to-end pipeline in five minutes.

View as Markdown

Install

pip install pictograph                # SDK + agent toolkit
pip install 'pictograph[cli]'         # + the `pictograph` command
pip install 'pictograph[inference]'   # + run trained models on your own hardware

Full extras table: Installation.

Get an API key

Sign in at app.pictograph.io, then Settings → API Keys → Create API Key. Pick a role (viewer / member / admin / owner) and copy the pk_live_... string. You can also reveal it again later from Settings.

export PICTOGRAPH_API_KEY=pk_live_...

Or run pictograph login, which prompts and writes ~/.pictograph/config.toml.

First call

Source: client.py

from pictograph import Client

client = Client()  # reads PICTOGRAPH_API_KEY
for dataset in client.datasets.list(limit=10):
    print(dataset.name, dataset.image_count)

Upload, annotate, train

Four explicit steps. Each returns a real object you can inspect, so a failure tells you which stage failed instead of handing back one opaque report.

from pictograph import Client, UploadReport, AnnotateReport, TrainingRun

client = Client()

uploaded: UploadReport = client.images.upload_from_directory(
    dataset_name="road-signs",
    directory="./road_signs",
)
print(f"{uploaded.images_uploaded} images uploaded")

labelled: AnnotateReport = client.auto_annotate.dataset(
    dataset_name="road-signs",
    classes=[("stop_sign", "bbox"), ("yield", "bbox")],
)
print(f"{labelled.annotations_added} annotations added")

client.exports.create(
    dataset_name="road-signs",
    name="road-signs-v1",
    format="pictograph",
    include_images=True,
    wait=True,
)

run: TrainingRun = client.training.create(
    dataset_name="road-signs",
    export_name="road-signs-v1",
    pipeline_type="yolox",
    name="road-signs-detector",
)
print("Trained model:", run.model_id or run.status)

Three things worth knowing:

  • Each method lives on the resource that owns its noun, so there is nothing extra to import.
  • A class is a (name, output_type) pair - bbox, polygon, or tag - because SAM3 needs to know what shape to produce.
  • Training runs on an export, never on a dataset directly. You create the export, see what went into it, then train it.

CLI equivalent

pictograph images upload-directory road-signs ./road_signs
pictograph auto-annotate batch road-signs --images 001.jpg,002.jpg --classes "stop_sign:bbox"
pictograph exports create road-signs --name road-signs-v1 -f pictograph --include-images
pictograph train start road-signs road-signs-v1 --pipeline yolox --gpu a10g
pictograph models download "road-signs-detector" -o ./yolox.onnx

Next

Copied to clipboard