Authentication

All generation requests need a Bearer key, and keys belong to your account. Log in with a magic link (we email it to you — no password), then create a key on the Account page. Or call the endpoint directly with your logged-in session cookie:

# requires a logged-in session — unauthenticated calls return 401
curl -X POST https://api.wagmi.photos/v1/keys/generate \
  -H "Cookie: wagmi_session=…" \
  -H "Content-Type: application/json" \
  -d '{ "label": "my-laptop" }'

{ "key": "sc-nA93…", "created_at": 1783468800 }

Key minting is rate-limited (10 per minute per IP). Store the key yourself — it is hashed (SHA-256) before it touches our database, so it cannot be shown again. Send it on every request as Authorization: Bearer sc-your-key.

Generate or fetch an image

The request shape matches the OpenAI Images API, so the official SDKs work by pointing base_url at https://api.wagmi.photos/v1. Your prompt is embedded with BGE and matched against the stored prompt of every image in the shared library; the closest match above your tolerance floor is served instantly.

Request body

Example

curl -X POST https://api.wagmi.photos/v1/images/generations \
  -H "Authorization: Bearer $WAGMI_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "a lighthouse in a storm",
    "cache_tolerance": 0.15,
    "generate_on_miss": false
  }'

Response — served from the library (200)

{
  "created": 1783468800,
  "data": [{ "url": "https://cdn.wagmi.photos/img/pd12m-8f31…" }],
  "shared_cache": {
    "result": "hit",
    "similarity": 0.93,
    "cost_saved_usd": 0.04,
    "model_used": "flux-schnell",
    "source": "pd12m",
    "sizes": { "thumb": "…", "medium": "…", "large": "…" },
    "original_url": "https://pd12m.s3.us-west-2.amazonaws.com/…"
  }
}

original_url is the external source image when one exists, and null for generated images.

Response — nothing close enough yet (202)

{
  "created": 1783468800,
  "data": [],
  "shared_cache": {
    "result": "pending",
    "similarity": 0,
    "cost_saved_usd": 0,
    "generation_queued": true
  }
}

Result values

How matching works

Matching is prompt-to-prompt: your prompt's BGE text embedding (bge-base-en-v1.5 on Workers AI) is compared by cosine similarity against the stored prompt embedding of every library image. Your cache_tolerance (clamped to 0–1) maps linearly to the similarity floor: floor = 0.87 − tolerance × (0.87 − 0.75), so tolerance 0 → floor 0.87 and tolerance 1 → floor 0.75. The single nearest library prompt is compared against that floor — at or above it you get a hit, below it an approximate. Realistic scores live in the ~0.7–0.95 band. See how semantic matching works for the full picture.

generate_on_miss semantics

Generation costs GPU time, so it is opt-out per request — but the queue is shared, and one prompt can be requested by many callers with different flags. The rules:

• Default is generate. A miss with the field unset (or true) queues the prompt for background generation.
• Opting out is per prompt, not per library. generate_on_miss: false still records the prompt and its demand count — it just tells the backfill to skip it.
• Generation wins. If the prompt is already queued for generation, a later request with false does not un-queue it. And if the prompt was stored opted-out, the first request that arrives with the field unset or true upgrades it, so it gets generated. Once a prompt wants generation, it stays wanted.
• The response tells you the effective state. shared_cache.generation_queued on pending and approximate responses reflects the merged result, not just your request — send false for a prompt someone else queued and you will get generation_queued: true back.

Errors

Health

Returns {"status":"ok"}. No authentication.

The only change

Swap your key for a wagmi.photos key (sc-…). Method names, the prompt field, and the way you read data[0].url stay exactly the same.

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.wagmi.photos/v1",
    api_key="sc-your-key",
)

img = client.images.generate(
    prompt="a lighthouse in a storm",
    extra_body={
        "cache_tolerance": 0.15,
        "generate_on_miss": True,
    },
)

print(img.data[0].url)
# raw response also carries a shared_cache block

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.wagmi.photos/v1",
  apiKey: "sc-your-key",
});

const img = await client.images.generate({
  prompt: "a lighthouse in a storm",
  cache_tolerance: 0.15,
  generate_on_miss: true,
});

console.log(img.data[0].url);

cURL

curl -X POST https://api.wagmi.photos/v1/images/generations \
  -H "Authorization: Bearer $WAGMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a lighthouse in a storm" }'

What stays the same, what you gain

Prompts match prompts

wagmi.photos embeds text prompts into a 768-dimensional space with the bge-base-en-v1.5 model, running on Workers AI at the edge. Every image in the library is indexed by the embedding of its own prompt — there are no image vectors. Because your prompt and the stored prompts are embedded by the same model, "a golden retriever" lands right next to the prompts that already produced one.

From prompt to match

1. Your prompt is normalized (trimmed, lowercased, whitespace collapsed).
2. BGE turns it into a 768-dim text vector at the edge.
3. Vectorize finds the single nearest stored prompt vector by cosine similarity.
4. That similarity is compared to your tolerance floor — at or above it is a hit; below it is approximate.

Similarity, illustrated

Illustrative cosine-similarity scores — in practice they land in a fairly narrow ~0.7–0.95 band. The generic prompt lands squarely on an existing prompt; the very specific one only finds a distant cousin.

Tolerance sets the floor

Your cache_tolerance (clamped to 0–1) maps linearly to the cosine-similarity floor a match must clear: floor = 0.87 − tolerance × (0.87 − 0.75).

At or above the floor you get a hit. Below it, the closest image is still served as approximate and the prompt is queued to generate (unless you opted out).

The skill file

Save it as SKILL.md or drop it straight into your agent's instructions. It hands the agent the endpoint, the request shape, and — the part that matters — how to act on hit / approximate / pending.

---
name: wagmi-photos-images
description: Fetch images cheaply and instantly from the wagmi.photos shared cache before paying to generate. Use whenever a task needs an image and "close enough" beats pixel-perfect.
---

# wagmi.photos — cache-first images

Get an image in ~100 ms for $0 by matching the shared library first. Only pay a
generator when the prompt is genuinely new or must be exact.

## When to use this
- You need a stock-style or illustrative image and an approximate match is fine.
- You want to avoid generation cost and latency by default.

Do NOT rely on the cache when the image must match a hyper-specific prompt
exactly (brand assets, precise composition). Use a dedicated image model there.

## Endpoint
POST https://api.wagmi.photos/v1/images/generations
  Authorization: Bearer sc-your-key
  Content-Type: application/json

Body fields:
- prompt            (string, required)
- cache_tolerance   (0..1, default 0.15)  lower = stricter match
- generate_on_miss  (bool, default true)  false = never spend GPU on a miss

## Call it
curl -X POST https://api.wagmi.photos/v1/images/generations \
  -H "Authorization: Bearer $WAGMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a vintage bicycle against a brick wall",
       "cache_tolerance": 0.15,
       "generate_on_miss": true}'

## Act on shared_cache.result
- "hit"          (HTTP 200): use data[0].url. Free and instant, you are done.
- "approximate"  (HTTP 200): a close image is in data[0].url. Use it only if it
                  fits the task; the exact prompt was queued for next time.
- "pending"      (HTTP 202): nothing close yet, data is empty. Generate with
                  your own model if you need an image now. The prompt was queued
                  (unless you opted out), so retrying later will hit for $0.

## Rules for the agent
1. Default to the cache. Send generate_on_miss=false when you only want free,
   instant results and a miss is acceptable.
2. Never treat "approximate" as exact — verify it matches the request.
3. On 202, do not block waiting. Proceed without an image or fall back to a real
   generator, then retry the same prompt later for a cheap hit.
4. Reuse one wagmi.photos key. It is hashed server-side; keep it secret.

How the agent should behave

Wire up a key

Keys are tied to your account. Log in with a magic link (email, no password), create a key on the Account page, then export it as WAGMI_KEY:

# 1. Log in at https://wagmi.photos/#/login (magic-link email)
# 2. Account → Create API key → copy the sc-… key (shown once)
export WAGMI_KEY=sc-…

Prefer the API? POST /v1/keys/generate also works with a logged-in session cookie — unauthenticated calls return 401. The full field reference lives in the API docs.