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 API always returns the closest match with a similarity score — threshold client-side if you need stricter matching; there is no cache_tolerance or generate_on_miss request parameter.

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"}'

Example — scoped to a collection

Pass collection to search inside one collection instead of the whole shared library. Official SDKs pass it via extra_body:

from openai import OpenAI

client = OpenAI(base_url="https://api.wagmi.photos/v1", api_key="YOUR_WAGMI_KEY")

img = client.images.generate(
    prompt="a watercolor fox in morning fog",
    extra_body={"collection": "col_abc123"},
)

Response — served from the library (200)

{
  "created": 1783468800,
  "data": [{ "url": "https://cdn.wagmi.photos/assets/pd12m-8f31…/image.webp" }],
  "shared_cache": {
    "result": "hit",
    "similarity": 0.93,
    "cost_saved_usd": 0.055,
    "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

Want a fresh image on your own schedule instead of waiting on demand-ranked backfill? Generate into a collection with your own BYOK provider key on the Collections tab — see Create images in your collections below.

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. The single nearest library prompt is compared against a fixed similarity floor (≈0.85, server-side — not a request parameter) — at or above it you get a hit, below it an approximate. Realistic scores live in the ~0.7–0.95 band. The API always returns the closest match with its similarity score in shared_cache; threshold client-side if you need stricter matching. See how semantic matching works for the full picture.

Background generation semantics

Every miss (approximate or pending) records the prompt's demand. There is no per-request opt-out — generation is decided centrally by demand-ranking, so the most-requested misses get built first by the shared backfill and become hits for everyone. shared_cache.generation_queued tells you whether this specific request's prompt is in that queue.

Errors

Create images in your collections

Generate a fresh image straight into a collection you own, using your own BYOK provider key set up on the Collections tab. Unlike POST /v1/images/generations, this endpoint always spends — it is the deliberate, async escape hatch for when you want your exact prompt now instead of waiting on demand-ranked backfill. It starts a background job and returns immediately; poll the ticket it hands back until it leaves queued/generating.

Start a generation

# Start a generation (requires your own provider key + a collection you own)
curl -X POST https://api.wagmi.photos/v1/collections/col_abc123/generations \
  -H "Authorization: Bearer sc-..." -H "Content-Type: application/json" \
  -d '{"prompt": "a watercolor fox in morning fog"}'
# -> 202 {"generation": {"id": "gen_...", "status": "generating", ...}, "byok": {"used": 3, "cap": 50, ...}}

Poll the ticket

# Poll the ticket until it leaves queued/generating
curl https://api.wagmi.photos/v1/generations/gen_... -H "Authorization: Bearer sc-..."
# -> {"generation": {"status": "succeeded", "image": {"url": "...", "thumb_url": "..."}}}

Statuses, refunds & ownership

A generation moves through queued → generating → succeeded or failed. Keep polling GET /v1/generations/:id while it is queued or generating; once it reaches a terminal status the response carries the image URLs (on succeeded) or an error string (on failed).

A generation that ends in failed is automatically refunded against your monthly cap — a failed attempt never counts toward used.

Collections are private capabilities: requesting a generation for a collection you don't own, or fetching a generation id you didn't create, returns 404 — the same as an unknown id.

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",
)

print(img.data[0].url)
# shared_cache always carries the closest match + a similarity score.
# Scope to a collection with extra_body={"collection": "col_..."}.

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",
});

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 a fixed match 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.

A fixed floor decides hit vs. approximate

The cosine-similarity floor a match must clear is fixed server-side (≈0.85, between 0.75 and 0.87) — it's not a request parameter, so there's no cache_tolerance to tune. The API always returns the closest match with its similarity score in shared_cache; threshold client-side if your use case needs something stricter.

At or above the floor you get a hit. Below it, the closest image is still served as approximate and the prompt is queued for demand-ranked background generation.

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)
- collection  (string, optional) scope the search to a collection you own (col_...)
- n           (integer, optional) only 1 is supported
- size        (string, optional) accepted for OpenAI compatibility, ignored

There is no cache_tolerance or generate_on_miss field. The API always returns
the closest match with a similarity score in shared_cache — threshold
client-side if the task needs stricter matching.

## 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"}'

## 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 demand-ranked
                  background generation.
- "pending"      (HTTP 202): nothing close yet, data is empty. Generate with
                  your own model if you need an image now. The prompt was
                  queued, so retrying later will hit for $0.

## Rules for the agent
1. Always check shared_cache.similarity before treating a result as good
   enough — the API never withholds a result, it just tells you how close it is.
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.