Quick start

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.

Hand it to your agent

Using Claude Code or Codex? Teach it the platform once:

pictograph agents install-skill   # Claude Code: the pictograph-cv skill
pictograph init                   # ./AGENTS.md for Codex and other agents

The agent runs the same loop as the rest of this page, one CLI step at a time, and hands you the drafts to review before it exports and trains. See Agents for what the skill covers and how to call your trained model as a tool. The steps below are that loop by hand.

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, draft, review, train

Five 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} draft annotations")

# Review: start with the drafts SAM3 was least sure of, and fix what
# is wrong in the app before you export.
for image in client.images.list(
    dataset_name="road-signs",
    min_confidence_lt=0.5,
):
    print("check:", image.filename)

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)

Four 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.
• Auto-annotations are drafts: review them in the app before you export.
• 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 images list road-signs --min-confidence-lt 0.5   # the drafts to check first
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

• Guides - upload, auto-annotate, tile, augment, train
• Local inference - run the model you just trained
• Agents - let Claude Code or Codex drive the loop, or build your own agent
• Annotation format - the canonical JSON schema