API reference

Getting started

The base URL is https://www.margensoftware.com and all endpoints live under /api/v1/data. Responses are JSON. Image bytes are never returned inline: a download returns a short-lived signed URL you fetch directly. The unversioned /api/data prefix still works as a permanent alias, so older integrations keep running.

You need a Margen account to get a key. Sign up at /eval/signup or log in at /eval/login, then manage keys at /keys.

1https://www.margensoftware.com/api/v1/data

Client SDK

The official Python SDK is on PyPI. Install it and construct a client with your key. The typed operations are list_benchmarks, get_catalog, list_items, download_item, and get_usage; a list value for any filter is sent as a comma-separated list. list_items returns a paginated wrapper you read through .result (so .result.data), while list_benchmarks, get_catalog, get_usage, and download_item return the object directly. For notebook workflows, margen.ergonomics adds iter_items / iter_lineages (paginate the whole result set) and download_selection (one-call bulk download to a folder). Other languages can call the REST endpoints directly (see the curl tab on each endpoint below).

1pip install margen

Authentication

Generate a key in the portal at /keys. The raw key is shown once; store it. Send it as a bearer token on every request.

1Authorization: Bearer mgn_live_xxxxxxxxxxxxxxxx

• Test keys (mgn_test_...): free, no credits needed, open to any account. A test key sees only the test sample, a fixed subset, so its catalog counts and available items differ from a live key.
• Live keys (mgn_live_...): the full corpus, credit-metered. Open to any account, no approval. Buying credits is the access, a live pull debits one credit per image. Enterprise or volume terms are arranged separately via a volume order.

Credits and pricing

• One credit pulls one image. Credits are prepaid and debited in real time at download. Buy credits in the portal at /keys (pick any amount; a flat per-image rate is shown at purchase).
• Credit usage is per unique image, per account. Your account is charged once per item id, and credits and ownership are account-scoped, so they survive a key rotation. Re-downloading an item your account already owns is free: the response carries charged: false and already_owned: true. So pulling the same selection twice never double-charges.
• To pull only images you do not already own, pass exclude_owned=true to /items; it also reports remaining/owned and a subset_exhausted message when you own the whole matching subset.
• A download is charged only on success; a retry with the same Idempotency-Key is never charged twice.
• With a zero balance a live-tier download returns 402 (code insufficient_credits) and delivers nothing. Top up in the portal.
• Test downloads are free and never touch your balance.

Rate limits

Each key has its own per-minute limit (set when you create the key, default 60). Exceeding it returns 429. Set a low limit to protect a credit balance from a runaway script.

Benchmarks

The data is organized into benchmarks. A benchmark is a versioned dataset (for example synthetic-face-v1) with its own set of queryable dimensions, the same way different models expose different parameters. You choose a benchmark, discover its dimensions, then query items within it. Every request that touches data takes a benchmark parameter.

List the benchmarks your key can query with /api/v1/data/benchmarks, then pass ?benchmark=<id> to /catalog (to see its dimensions and values) and /items (to select images). The dimensions differ per benchmark; /catalog is always the source of truth for what a given benchmark supports.

Available benchmarks

For full dataset specs (composition, image spec, labeling) see the Synthetic Face Image benchmark page.

Selecting images

Pulling data is three steps: discover a benchmark's dimensions with /catalog, select the items you want with /items, then fetch each with /download. Selection happens entirely in the /items query string, so a request fully describes the set you are pulling. The recipes below are copy-ready against synthetic-face-v1.

Two rules cover every query: a comma-separated value matches any of the listed values (OR within a dimension), and separate parameters must all hold (AND across dimensions). Omit a dimension to include all of its values.

Two terms used throughout: a cell is one skin-tone x gender combination, and a lineage is a sourced real image plus every fake and perturbed variant derived from it, all sharing one source_real_id.

1items = list(iter_items(
2    client, benchmark="synthetic-face-v1",
3    kind="fake", skin_tone="dark", gender="female", perturbation="clean",
4))

1{
2  "object": "list",
3  "total": 12,
4  "has_more": true,
5  "benchmark": "synthetic-face-v1",
6  "data": [
7    { "object": "attack_data_item", "id": "8f3c1d2e-...",
8      "kind": "fake", "skin_tone": "dark", "gender": "female",
9      "generator": "diffusion-v1", "perturbation": "clean",
10      "layer": "clean", "base_id": "b2d4e6f8-...", "source_real_id": "real_0001" }
11  ]
12}

1items = list(iter_items(
2    client, benchmark="synthetic-face-v1", kind="fake",
3    skin_tone=["dark", "brown"], perturbation=["jpeg_q70", "jpeg_q80"],
4))

1{
2  "object": "list",
3  "total": 64,
4  "has_more": false,
5  "benchmark": "synthetic-face-v1",
6  "applied_filters": {
7    "skin_tone": ["dark","brown"], "kind": ["fake"],
8    "perturbation": ["jpeg_q70","jpeg_q80"], "gender": null
9  },
10  "data": [ /* dark+brown x q70+q80 fakes */ ]
11}

1items = list(iter_items(
2    client, benchmark="synthetic-face-v1", source_real_id="real_0001",
3))

1{
2  "object": "list",
3  "benchmark": "synthetic-face-v1",
4  "data": [
5    { "object": "attack_data_item", "id": "r1a2b3c4-...", "kind": "real",
6      "perturbation": "clean", "base_id": "img_r1a2", "source_real_id": "real_0001" },
7    { "object": "attack_data_item", "id": "f5d6e7f8-...", "kind": "fake",
8      "perturbation": "clean", "generator": "diffusion-v1",
9      "base_id": "img_f5d6", "source_real_id": "real_0001" },
10    { "object": "attack_data_item", "id": "f9a0b1c2-...", "kind": "fake",
11      "perturbation": "fb_pipeline", "generator": "diffusion-v1",
12      "base_id": "img_f5d6", "source_real_id": "real_0001" }
13  ]
14}

1# you have an item; pull every perturbation of that same base image
2variants = list(iter_items(
3    client, benchmark="synthetic-face-v1", base_id=item.base_id,
4))
5# or jump straight to one condition of the same image:
6one = client.list_items(
7    benchmark="synthetic-face-v1", base_id=item.base_id, perturbation="jpeg_q70",
8).result.data[0]

1{
2  "object": "list",
3  "benchmark": "synthetic-face-v1",
4  "data": [
5    { "object": "attack_data_item", "id": "f7c8d9e0-...", "kind": "fake",
6      "perturbation": "jpeg_q70", "generator": "diffusion-v1",
7      "base_id": "img_f5d6", "source_real_id": "real_0001" }
8  ]
9}

Endpoints

1benchmarks = client.list_benchmarks().data

1catalog = client.get_catalog(benchmark="synthetic-face-v1")

1# fake, dark or brown cell, JPEG q70 or q80, first 2
2page = client.list_items(
3    benchmark="synthetic-face-v1",
4    kind="fake",
5    skin_tone=["dark", "brown"],
6    perturbation=["jpeg_q70", "jpeg_q80"],
7    limit=2,
8).result
9for item in page.data:
10    print(item.id, item.skin_tone, item.perturbation)

1import urllib.request
2dl = client.download_item(item_id="8f3c1d2e-...")   # Idempotency-Key set for you
3# dl.url is a short-lived signed URL; fetch it with no auth header
4urllib.request.urlretrieve(dl.url, "image.jpg")

1usage = client.get_usage()   # usage.tier, usage.balance

Objects

The resources returned by the API. Every object carries an object discriminator. The paginated /items list wraps results in the standard envelope { object: "list", data: [...], has_more, next_cursor, total }. /benchmarks is a simple list ({ object: "list", data: [...] }) and is not paginated, so it carries no has_more or next_cursor. Fields shared across benchmarks are typed; benchmark-specific fields are carried in attributes.

The /items list also echoes the query back at the top level: benchmark, mode (offset | cursor | lineage), applied_filters, and limit / offset / limit_clamped. In cursor and lineage modes total is null (the full set is not counted); lineage mode adds total_lineages and lineages (the count on the current page). For future benchmarks, an attributes-backed dimension appears in /catalog with source: attribute and is queried by its key like any other dimension; for synthetic-face-v1 there are none, so attributes is always {}.

Errors

Every error body carries a stable machine-readable code alongside the human-readable error message. Branch on code, not on the message text or the HTTP status alone (one status can map to more than one code).

Two things are deliberately not errors: owning every item in a selection (a 200 with subset_exhausted: true on /items?exclude_owned=true) and re-downloading an item you already own (a 200 with charged: false). Neither returns an error code.

Quickstart

Create a key at /keys, then pull with the SDK (pip install margen).

1import urllib.request
2from margen import Margen
3 
4client = Margen(bearer_auth="mgn_test_...")   # your key from /keys
5 
6# one dark female fake, clean, from synthetic-face-v1
7item = client.list_items(
8    benchmark="synthetic-face-v1",
9    kind="fake", skin_tone="dark", gender="female",
10    perturbation="clean", limit=1,
11).result.data[0]
12 
13# download it (debits 1 credit on the live tier; free on test)
14dl = client.download_item(item_id=item.id)
15urllib.request.urlretrieve(dl.url, "image.jpg")   # signed URL, no auth header
16print("saved image.jpg, balance:", dl.balance)