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 {}.
The benchmark object
Returned by /api/v1/data/benchmarks and /api/v1/data/catalog. Describes a benchmark and the dimensions it exposes.
| Field | Type | Description |
|---|---|---|
object | string | Always "benchmark". |
code | string | Stable citable alias (e.g. MG-SYN-01); accepted as the benchmark parameter alongside id. |
id | string | Versioned benchmark id, used as the benchmark parameter (e.g. synthetic-face-v1). |
product | string | Portfolio grouping (faces, swaps, puppets, liveness). |
title | string | Human-readable name. |
description | string | What the benchmark contains. |
dimensions | array | The queryable dimensions. On /benchmarks, an array of dimension key strings; on /catalog, the full objects (key, label, source column|attribute, and either values [{value,label}] for a fixed set or lineage:true for a lineage key). |
The item object
Returned by /api/v1/data/items and /api/v1/data/download/:itemId. One deliverable image. Fields that do not apply to a benchmark are null.
| Field | Type | Description |
|---|---|---|
object | string | Always "attack_data_item". |
id | string | Item id. Pass to /api/v1/data/download/:itemId to fetch the image. |
benchmark | string | The benchmark this item belongs to. |
kind | string | real (a genuine, unmodified photo) or fake (AI-generated). |
skin_tone | string | null | Skin-tone band (6-level light-to-dark scale). |
gender | string | null | Demographic cell gender. |
generator | string | null | Generator model (fake items only). |
perturbation | string | null | Condition applied (e.g. clean, jpeg_q70, fb_pipeline). |
layer | string | null | Perturbation layer (clean, layer1, layer2, layer2_recropped). |
scene | string | null | Shot context; benchmark-specific (synthetic-face-v1: indoor | outdoor | selfie). null for reals. |
ttp_tactic | string | null | The attacker's goal behind the item (e.g. impersonation). null for reals. |
ttp_technique | string | null | How the tactic is realized (e.g. identity_conditioned_synthesis, identity_preserving_edit), so a detector failure can be debugged, not just counted. null for reals. |
base_id | string | null | The base image this variant derives from. Hold base_id and change perturbation to pull another condition of the SAME image; all perturbations of one image share it. |
source_real_id | string | null | Lineage key: the sourced real image this item descends from. All variants of one source share it. |
identity_id | string | null | The reconciled person identity, spanning all of a person's images and videos (broader than source_real_id). A real and its identity-preserving fakes share it. Use distinct_identities=true for one item per person; null for a few unresolved rows. |
attributes | object | Benchmark-specific fields as key/value pairs; empty {} when the benchmark has none. |
metadata | object | null | The full per-image label object (skin tone incl. ITA, gender and cross-checks, age/race, scene/face/occlusion and confidences, difficulty, image spec). Present only when the request passes include=metadata; omitted otherwise. Flat and stable, so it builds a consistent table; /catalog lists the fields. |
The download object
Returned by /api/v1/data/download/:itemId. Carries the short-lived signed URL plus the item and updated balance.
| Field | Type | Description |
|---|---|---|
object | string | Always "download". |
url | string | Short-lived signed URL that delivers one JPEG image. Fetch it directly with no auth header. |
expires_in | number | Seconds until the signed URL expires (e.g. 300). |
item | object | The item object for the downloaded image. |
balance | number | null | Credit balance after this download (live tier). null on the test tier, which is free. |
charged | boolean | true if this pull debited a credit. false for free test items and for re-downloads of an item you already own. |
already_owned | boolean | true if you had already pulled this item; the URL is returned again for free, no debit. |