# AI Wave

> A normalized feed of AI model changes: new releases, price changes, API changes and
> deprecations, assembled from vendor release notes, Hugging Face, the OpenRouter catalog,
> GitHub and the LiteLLM price map. Chat models and non-chat ones alike: embedding, rerank,
> transcription, speech and video. Duplicates for the same model are merged; each item is
> marked official or pending review.

## What this is good for

- "Which model should I use for X?": benchmark scores and price in one call, so the
  trade-off is visible without stitching two sources together.
- "What would this cost me a month?": token prices turned into a monthly bill, USD and KRW.
- "Did anything I depend on change?": poll the change feed with `since`.
- "Is this model still available?": deprecations are detected when a model stays absent
  from the catalog for 24 hours.
- "Was this cheaper last month?": price history; the public catalog only shows today.

## What this is NOT good for

Reading the raw catalog: current price and context come from OpenRouter, so calling
https://openrouter.ai/api/v1/models directly is simpler if that is all you need. What is
added here is the change history, the provenance marking, the benchmark join and the
cost translation.

Running benchmarks: we do not run them. Scores are Artificial Analysis' published
figures, joined to catalog ids. Attribute them to Artificial Analysis, not to us.

## Access

The MCP server (https://aiwave.elopstudio.com/api/mcp) works without a key, up to 100 tool
calls/day per IP. The REST endpoints and anything beyond that need an API key.
Create one at https://aiwave.elopstudio.com/member (sign-in needed).
Send it as `Authorization: Bearer <key>`, or as `x-api-key: <key>` when you sit behind a
gateway that reserves the Authorization header for itself.
Free tier: 1000 calls/day. Remaining calls come back in
`x-ratelimit-remaining`.

## Endpoints

- https://aiwave.elopstudio.com/api/openapi.json: OpenAPI 3.1 spec (read this first if you are a tool)
- https://aiwave.elopstudio.com/api/v1/changes?since=<unix>: change feed, oldest first, returns `latest` to
  feed back on the next poll. Use `latest` as the cursor, never an item's
  `detectedAt`, which is when the change happened per the source and can point months
  back for a model we only just found.
- https://aiwave.elopstudio.com/api/v1/models?vendor=&maxInputPrice=&minContext=&outputs=: model catalog with
  attention ranking. `outputs` is text|image|audio|video, meaning what the model *produces*, not
  what it can read. A model that takes video and writes text is `text`.
- https://aiwave.elopstudio.com/api/v1/models/{slug}/history: price history (only recorded when it changes)
- https://aiwave.elopstudio.com/api/v1/digest: today in one payload: top 5, climbers, price changes (24h),
  newly listed (7d). Use this instead of re-deriving it from the change feed.
- https://aiwave.elopstudio.com/api/mcp: MCP server over JSON-RPC/HTTP. Tools: list_model_changes, get_model,
  get_price_history, search_models, compare_models, estimate_cost, get_today,
  find_replacement

## Webhooks

Polling `/api/v1/changes` works. If you run a service that must react the moment a
price moves, register a URL instead and we push to you.

- POST https://aiwave.elopstudio.com/api/webhooks {url, eventTypes?, vendor?} → returns `secret` once
- GET https://aiwave.elopstudio.com/api/webhooks → your endpoints (the secret is never returned again)
- DELETE https://aiwave.elopstudio.com/api/webhooks/{id}
- POST https://aiwave.elopstudio.com/api/webhooks/{id} → re-enable one we disabled

We POST one JSON body per event, with these headers:

- `x-aiwave-event`: change event id
- `x-aiwave-delivery`: unique per attempt
- `x-aiwave-timestamp`: unix seconds
- `x-aiwave-signature`: `sha256=<hex>`, HMAC-SHA256 of `{timestamp}.{body}` with your secret

Verify the signature and reject anything older than 300 seconds. We follow no
redirects, time out at 8s, and count only 2xx as delivered. The same event is never
sent twice to the same URL. After 10 consecutive failures we disable the endpoint, and
re-enable it with the POST above once your side is back.

## Choosing a tool

- Comparing candidates → `compare_models` (aligns fields; one call, not N)
- Narrowing by budget or a single skill → `search_models` with `sortBy`
- Needing a specific medium → `search_models` with `outputs` (makes it) or `accepts` (reads it)
- Turning token prices into a monthly bill → `estimate_cost`
- Watching for breakage → `list_model_changes` with `since`
- "What happened today?" → `get_today` (one call; already summarized)
- "This model is gone. Now what?" → `find_replacement` (closest measured performance)

## MCP

Remote (no install, no key needed to try it):

    { "type": "http", "url": "https://aiwave.elopstudio.com/api/mcp" }

With a key, for higher limits:

    { "type": "http", "url": "https://aiwave.elopstudio.com/api/mcp",
      "headers": { "Authorization": "Bearer <key>" } }

Local:

    { "command": "npx", "args": ["-y", "@elopstudio/ai-wave-mcp"],
      "env": { "AIWAVE_API_KEY": "<key>" } }

## Caveats

- `buzz` measures how much a model is being talked about right now (listing recency,
  news, opinions, vendor activity). It is not a quality or benchmark score. Do not
  present it as one.
- A null benchmark subject means the model was not given that test, not that it scored
  low. Frontier models often skip saturated tests such as AIME. Saying "it scored 0" or
  "it is weak at math" from a null is wrong.
- `overall` is an index, not a percentage: leaders sit near 53 and nothing reaches 100.
  Subject scores are percent correct. Do not compare the two scales, and do not compare
  across subjects: each is a different test.
- Items marked `pending` were inferred from an intermediary catalog, not announced by the
  vendor. Say so when you repeat them.
- Deprecation is inferred from a model disappearing from the catalog. It is a strong hint,
  not a vendor statement.
- Prices are not all per token. Read `pricing.unit` before you print or multiply a price:
  it is token, second, character, image or query, and `mode` says what kind of model it is
  (chat, embedding, rerank, audio_transcription, audio_speech, video_generation). Only the
  token unit carries the legacy `inputPerMillion` field. Presenting a per-second video
  price as a per-million-token price is wrong by a factor of a million.

## Docs

- https://aiwave.elopstudio.com/api-docs: human-readable guide