IEXDG × Shutterstock
API Reference

The discovery that flipped the architecture

On 2026-05-15, Dr. DNicole escalated 11 days of visual-direction frustration: the brain kept generating cream-and-gold off-brand cards, the corrections were reactive, and the DEMO_ROTATION on content_drop_v3 kept firing the same three avatars in positions 0, 1, 2. Two weeks of memos treated this as a prompt-engineering problem. It was a corpus problem. The fix was not better words. The fix was finding what her own eye had already said yes to.

Who owns what, with what allotments

Inventory of the Shutterstock account, subscriptions, and download history attached to IEXDG, as verified against live API calls on 2026-05-26.

Active subscriptions on 2026-05-26

The user-scope tier is the one that matters

Most public Shutterstock API examples on the internet show a two-line cURL against v2/images/search with an OAuth client_credentials grant. That tier sees catalog metadata and nothing else. The tier we hold is one level up: a long-lived user-scope bearer token. It is the difference between renting a search index and walking into the room with her wallet.

Credentials on disk

Token shape (what the v2 bearer looks like)

# The user-scope token is a self-describing base64 string starting with v2/
v2/Y24wbjdqOVlTWGZLRk5ma052czg3UVVzbExTR1F0SnkvNDgzMDkzODQ3L2N1c3RvbWVy...
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^^^^^^^^
       client_id (cn0n7j9YSXfKFNfkNvs87QUslLSGQtJy)     customer_id (483093847)

# Validity: long-lived. Expires only on Dr. DNicole's account password change.
# Scope claims (per the master_logins.txt registration record):
#   licenses.create  collections.edit  user.email  user.view  subscriptions.view

Fallback OAuth client_credentials exchange

curl 'https://api.shutterstock.com/v2/oauth/access_token' \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=$IEXDG_SHUTTERSTOCK_CLIENT_ID' \
  -d 'client_secret=$IEXDG_SHUTTERSTOCK_CLIENT_SECRET' \
  -d 'grant_type=client_credentials' \
  -d 'scope='

# Returns: { "access_token": "v2/...", "expires_in": 2592000, "scope": "" }
# Note: empty scope = search-only tier. Cannot read licenses.
# Use this ONLY when the user-scope bearer fails. See iexdg_apis.py:213.

Every Shutterstock surface the IEXDG stack calls

A single source of truth for which endpoints the pipeline already calls, which ones today's probe added to the inventory, and what each one returns. All paths assume base https://api.shutterstock.com.

Two cURL recipes worth keeping at hand

curl 'https://api.shutterstock.com/v2/user' \
  -H "Authorization: Bearer $TOKEN"

# Returns:
# { "id": "483093847",
#   "username": "drdnicole96",
#   "display_name": "Denean Fields" }

curl 'https://api.shutterstock.com/v2/images/licenses?per_page=100&page=1' \
  -H "Authorization: Bearer $TOKEN"

# Returns:
# { "total_count": 73,
#   "data": [ { id, image.id, download_time, license, ... }, ... ] }

The 73-download corpus, anatomized

A single API call against v2/images/licenses turned 11 days of guesswork into a concrete training set. Below is the shape of the data, the signal worth extracting, and the one image that punches above its weight.

License payload shape

{
  "total_count": 73,
  "page": 1,
  "per_page": 100,
  "data": [
    {
      "id": "e13fe8731cdd6e6315370fa798a8462ff0",
      "user": { "username": "drdnicole96" },
      "license": "standard",
      "download_time": "2026-05-14T12:07:07.000Z",
      "is_downloadable": true,
      "image": {
        "id": "2408698777",
        "format": { "size": "huge" }
      },
      "subscription_id": "MDcwODRhYzVjZjU3..."
    },
    ...
  ]
}

Signals extractable from a single page

The 73-download taste heatmap

Every license event she has ever logged, rendered as a single grid. Each cell is one unique image. Cell warmth equals how many times she returned to that image and paid again. The brightest cell is image 265888400, downloaded thirteen separate times. Cool cells are one-and-done. The shape of the heat map IS the shape of her operational taste.

Shutterstock as fallback, as reference corpus, or both

As of 2026-05-27, the pipeline flips: Shutterstock is the PRIMARY image source. The May 27 test-fire of the original .NEW_PILLAR_REWIRE (OpenAI-primary) reproduced the May 15 failure mode (system claims Shutterstock and ships AI). Robert pulled back the 10-second peek that same morning (Gmail msg 19e696af6e250e08), halted the cron, and shipped the Shutterstock-primary sibling (.SHUTTERSTOCK_PRIMARY). Today the system uses real photographer-shot Shutterstock photos licensed via Dr. DNicole's drdnicole96 subscription as the default source; OpenAI gpt-image-1 only fires if all 10 Shutterstock candidates per pillar fail the visual gate.

Comparison across 8 axes

From operational taste to aspirational taste

The 73-download corpus is what she did when the deadline was tomorrow. Her May 2026 rubric is what she wants when she gets to choose. These are two different brands. The architecture has to honor both: respect the corpus as a NO board, build the YES board from her stated rubric, and pivot the matching method to the only model that can read the qualitative difference.

The post-generation gate architecture

Today the pipeline is generator, copy gate, ship. The proposed architecture inserts an image gate between generation and copy gate, and makes both gates hard, blocking, fail-closed. A regenerate-on-fail loop with a maximum of three attempts keeps the pipeline self-healing.

Why centroid first, k-NN later

Reference Python (the gate function)

def visual_gate_score(candidate_img_path: Path, centroid: np.ndarray) -> float:
    """Return cosine similarity in [-1, 1]. Threshold gate at >= 0.72."""
    emb = embed_via_claude_vision(candidate_img_path)   # ~$0.001 per call
    return float(np.dot(emb, centroid) / (np.linalg.norm(emb) * np.linalg.norm(centroid)))

def generate_with_gate(prompt: str, centroid: np.ndarray, max_tries: int = 3) -> Path | None:
    for attempt in range(max_tries):
        img = openai_gpt_image_1(prompt)                # or shutterstock fallback
        score = visual_gate_score(img, centroid)
        if score >= 0.72:
            return img
        prompt = strengthen_brand_constraints(prompt, attempt)
    # Fail closed. Never ship an off-brand image.
    return None

How the May 27 fixes connect to the Shutterstock API

Five named fixes shipped on 2026-05-27 to convert the Shutterstock-primary doctrine from claim to running pipeline. Each fix touches a specific Shutterstock surface (or sits adjacent to one). This map shows the exact endpoint or local boundary each fix modifies, what the fix does, and the data that flows between them. Topic-native to this doc: every arrow goes through a Shutterstock API behavior or a local gate that sits between two Shutterstock calls. Not borrowed from Flywheel, ELCC, or Pipeline diagrams.

The Shutterstock fuckup chronicle

Honest log of every Shutterstock-domain mistake from 2026-05-15 (Dr. DNicole's escalation) through 2026-05-27 (Shutterstock-primary stand-up plus the May 27 reply round). Ten incidents, named clearly, fixes shown per incident. Cataloged here so the next session, the next agent, and the next reader can read one timeline instead of scattered breadcrumbs.

The visual gate loop

The gate is not a one-shot filter. It is a self-reinforcing loop. Every drop she peeks at returns one signal: YES, NO, or silence. Every signal updates the centroids. Every centroid update tightens the next score. By the thirtieth drop the gate is reading her eye more reliably than the original brief did. The diagram below is the production topology, six stations on a closed cycle plus one off-loop quarantine for everything the gate refuses to ship.

Ship it in six steps

Sequence to take this doc from architecture to running pipeline. Each step is independently verifiable. Total wall-clock: 3 to 4 working hours plus Dr. DNicole's 10-second peek.

python source/scripts/automations/shutterstock_saved_photos_puller.py --from-licenses

python source/scripts/automations/embed_reference_corpus.py \
  --src source/assets/dnicole_references/YES_FROM_LICENSES \
  --provider claude_vision

Cost model · the whole bulletproof for under a dollar a month

Open items + carry-forward