# BlockRun API (api.blockrun.ai) — API-key entry point to the routing and payment layer for AI

> BlockRun is the routing and payment layer for AI. One OpenAI-compatible endpoint routes to 100+ LLMs plus image, video, music and speech generation, web search, prediction-market and on-chain data, and multi-chain RPC. This host is the account-balance entry point: authenticate with an API key and pay from a BlockRun account funded by card or wire — no wallet signature per call. The same services are also sold per call in USDC over x402 at https://blockrun.ai (Base), https://sol.blockrun.ai (Solana) and https://arc.blockrun.ai (Arc).

## Base URL
- API: https://api.blockrun.ai/v1
- Auth: `Authorization: Bearer $BLOCKRUN_API_KEY`
- Get a key: register at https://user.blockrun.ai, create a key at https://user.blockrun.ai/dashboard/keys, add credit at https://user.blockrun.ai/dashboard/credits
- This document: https://api.blockrun.ai/llms.txt · OpenAPI 3.1: https://api.blockrun.ai/openapi.json · Discovery (JSON): https://api.blockrun.ai/discovery · Agent card: https://api.blockrun.ai/.well-known/agent-card.json

## First call

```
curl https://api.blockrun.ai/v1/chat/completions \
  -H "Authorization: Bearer $BLOCKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"hello"}]}'
```

Point any OpenAI SDK at `base_url="https://api.blockrun.ai/v1"`; point the Anthropic SDK at the same base URL for `/v1/messages`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /v1/models | Live model catalog with per-token prices. Free. |
| GET | /v1/images/models | Image/video model catalog with per-call prices. Free. |
| POST | /v1/chat/completions | OpenAI Chat Completions for every model, streaming and tools supported. Billed per token. |
| POST | /v1/messages | Anthropic Messages, native envelopes. Billed per token. |
| POST | /v1/responses | OpenAI Responses API. Billed per token. |
| POST | /v1/images/generations | Image generation. Billed per image. |
| POST | /v1/videos/generations | Video generation; returns a `poll_url` — use it verbatim with the same key. Billed per second; reference video/audio clips add a per-clip surcharge, and the 202 body's `price.amount` is the exact quote. |
| POST | /v1/audio/speech | Text to speech. Billed per character. |
| POST | /v1/search | Live web / news / X search. Flat fee per call. |
| POST | /v1/decisions | Typed judgments for agents — yes/no, choice and score — over text or images, with probabilities. OpenAI Decisions API compatible. Free for any registered key, 1000 calls per account per hour. |
| POST | /v1/decide | The same judgments in System One's wire format (`noul`/`choice`/`score` over `state`), kept for existing callers. Free; shares the `/v1/decisions` quota. |
| GET | /v1/usage | One row per request; `window=today|24h|7d|30d` or `from`/`to`. Free. |
| GET | /v1/usage.csv | The same rows as a CSV file, whole window, one download. Free. |
| GET | /v1/usage/summary | Totals over a window: per day, model, endpoint, key. Free. |
| GET | /v1/balance | Available balance, recorded spend and open reservations. Free. |
| GET | /v1/credits | The balance, plus OpenRouter's `data: { total_credits, total_usage }`. Free. |
| GET | /v1/key | OpenRouter's GET /key: this key's usage today / this week / this month / lifetime, the account's limit and budgets. Free. |
| GET | /v1/activity | OpenRouter's GET /activity: spend per UTC day and model, last 30 completed days; `date`, `api_key_hash`. Free. |
| GET | /v1/generation?id= | OpenRouter's GET /generation: one call's cost and tokens by response `id` or `x-blockrun-request-id`; last 2 days. Free. |

The data and tool services published at https://blockrun.ai/llms.txt (Exa, prediction markets, DefiLlama, multi-chain RPC, phone) are reachable here under the same `/v1/...` paths with Bearer auth; the price sheet is the one `GET /v1/models` and `GET /api/pricing` on the gateway publish.

## Decisions

`POST /v1/decisions` answers typed questions about a piece of input — a message, a tool call, a document, a screenshot — instead of generating text. It is the OpenAI Decisions API contract unchanged (model `gpt-6-luna`), so the OpenAI SDK works with `base_url` set to `https://api.blockrun.ai/v1` and your BlockRun key. Three question types, several per call:

- `predicate` — `{type, name, instructions}` → `probability` that it is true.
- `choice` — adds `choices: [{value, description}]` → the `choice`, per-option `probabilities`, and a `confidence`.
- `score` — adds `levels: [{label, description}]` (ordered, indexed from 0) → a `score` (probability-weighted level), per-level `probabilities`, and a `confidence`.

`input` is a string, or messages carrying text and inline base64 images (no image URLs): at most 120,000 characters of text and 8 images per call. `questions`: at most 64 per call, 30,000 characters in all (every field counted), and 255 choices or levels each. Anything over a cap is refused with a 400 before anything runs. Only `model`, `input`, `questions` and `metadata` are forwarded. An answer can also come back as `type: "refusal"`.

```
curl https://api.blockrun.ai/v1/decisions \
  -H "Authorization: Bearer $BLOCKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-luna","input":"Help! My payouts have been failing for 3 days.","questions":[{"type":"predicate","name":"is_urgent","instructions":"Does this convey urgency? True only if it is explicitly time-sensitive."},{"type":"choice","name":"department","instructions":"Which team should handle this?","choices":[{"value":"billing","description":"Payments, refunds"},{"value":"technical","description":"Bugs, outages"}]}]}'
```

`POST /v1/decide` still accepts System One's wire format (`state` plus `questions` keyed by id; `noul`, `choice`, `score` with `criteria`) and answers in it, served by the same model. New integrations should use `/v1/decisions`.

Free for any registered key — no balance, no card, no wallet: register at https://user.blockrun.ai, create a key at https://user.blockrun.ai/dashboard/keys, and call. 1000 calls per account per hour across both paths, `x-ratelimit-remaining` on every response.

## Billing
- Metered at exact upstream usage × the published price sheet; chat tokens carry no platform margin on self-service accounts (see your contract for provisioned accounts).
- No per-call transaction fee and no minimum charge on key-metered accounts: you pay usage × rate and nothing is added to it.
- Long context: some models reprice the WHOLE request above a prompt-token threshold (OpenAI: above 272K, at 2x input and 1.5x output). Thresholds and rates are per model in `GET https://blockrun.ai/api/pricing` (`longContextThreshold`, `longContextThresholdInclusive`, `longContext*Price`); `GET /v1/models` does not repeat them.
- Flex: send `service_tier: "flex"` for half the rate on every token class, including the long-context rate. Billed from the tier the response reports, not the tier asked for. A Flex ask with no capacity returns 429 `resource_unavailable`, carries no usage and is not charged — retry with backoff or drop the field for standard processing. A successful upstream answer that does not report `service_tier: "flex"` is refused with 502 `FLEX_TIER_UNCONFIRMED` and not charged; it is never served at the standard rate in Flex's name (streams are checked on their first chunk). Availability is the provider's limited beta. A Flex ask is refused with 400 `FLEX_TIER_UNSUPPORTED` before any charge, never answered by a different model, when the model offers no Flex (`openai/gpt-4.1*`, `openai/gpt-4o*`, `openai/o1`, `openai/o3-mini`, `openai/chat-latest`, `openai/gpt-5.3-codex`) or cannot report the served tier (`openai/gpt-5.6-*-pro`, partner pool; `openai/gpt-oss-*`, NVIDIA) — drop the field to run them at standard rates.
- `service_tier` on each `/v1/usage` row states the tier that line was billed at; absent means standard.
- `reasoning_effort` on each `/v1/usage` row is the effort the request asked for, as sent (for grouping spend; the cost is already in the output tokens). Absent when none was sent.
- A request that fails on our side is not charged. Truncated or malformed streams produce an error event and are not recorded as a charge.
- `/v1/usage` is the authoritative record; HTTP status alone does not establish a successful stream.

## Links
- Website: https://blockrun.ai · Docs: https://blockrun.ai/docs/getting-started/enterprise-api · Terms: https://blockrun.ai/terms (plain-text pointer for agents: https://api.blockrun.ai/terms.txt) · Contact: hello@blockrun.ai