HERO RUN — DEVELOPER DOCS
https://hero-run.vercel.app

If you can call OpenAI, you can call Hero Run. One base URL, one key, 375+ AI models
(text, image, video, audio) across 10 inference gateways. Pay per call in the $HERO token.
No per-provider accounts or API keys. Fees fund open-source AI model training.

================================================================================
QUICKSTART
================================================================================

Base URL : https://hero-run.vercel.app/v1
Auth     : Authorization: Bearer hr_live_...   (mint a key at https://hero-run.vercel.app/keys)
Model    : "auto" = multi-gateway router (right-sized model, one flat price),
           or any id from GET https://hero-run.vercel.app/v1/models

--- Python (OpenAI SDK) ---
from openai import OpenAI

client = OpenAI(base_url="https://hero-run.vercel.app/v1", api_key="hr_live_...")
r = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "hello"}],
)
print(r.choices[0].message.content)

--- JavaScript / TypeScript (OpenAI SDK) ---
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://hero-run.vercel.app/v1", apiKey: "hr_live_..." });
const r = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "hello" }],
});
console.log(r.choices[0].message.content);

--- curl ---
curl https://hero-run.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer hr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}],"stream":false}'

================================================================================
OFFICIAL SDK — hero-run-ai
================================================================================

npm install hero-run-ai

import { createHeroRun } from "hero-run-ai";
const hero = createHeroRun({ apiKey: "hr_live_..." });
const { text } = await hero.chat([{ role: "user", content: "hi" }]);

Zero-dependency JS/TS client: chat, streaming, image/video/audio generation, a Vercel
AI SDK provider, and a drop-in <HeroRunChat/> React widget. Docs: npmjs.com/package/hero-run-ai

================================================================================
ROUTING MODES
================================================================================

auto        Multi-gateway router picks a right-sized model at one flat price.
<model id>  Pin a specific model (e.g. anthropic/claude-fable-5). See /v1/models.

The router load-balances across gateways (OpenRouter, Groq, Cerebras, Fireworks,
Baseten, WaveSpeed, Wafer and more) and falls back if one is slow or down.

================================================================================
FUNCTION CALLING / TOOLS
================================================================================

Pass OpenAI-format tools + tool_choice; they are forwarded to the routed gateway.
tool_calls come back with finish_reason "tool_calls". Send results as role:"tool"
messages as usual. (Tool turns respond unstreamed.)

tools = [{"type": "function", "function": {
  "name": "get_weather",
  "description": "Get weather for a city",
  "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
}}]

Works with the OpenAI SDK, Vercel AI SDK, LangChain, CrewAI, and LlamaIndex.

================================================================================
IMAGES, AUDIO & VIDEO
================================================================================

Native HTTP endpoint handles every modality:

POST https://hero-run.vercel.app/api/run
  -H "x-api-key: hr_live_..."
  -H "Content-Type: application/json"
  -d '{"model":"google/gemini-3-pro-image","input":"a red panda astronaut","kind":"image"}'

kind: "text" | "image" | "video" | "audio". Image/video/audio results come back as a
URL or data URI. List models by kind: GET https://hero-run.vercel.app/v1/models

================================================================================
NATIVE HTTP API
================================================================================

POST https://hero-run.vercel.app/api/run        Run any model.  Body: {model, input, kind, consent?}
GET  https://hero-run.vercel.app/v1/models      List all models + $HERO price.
POST https://hero-run.vercel.app/v1/chat/completions   OpenAI-compatible chat (streaming supported).

Auth: "x-api-key: hr_live_..." (native) or "Authorization: Bearer hr_live_..." (/v1).
Every paid call accepts consent:true to contribute prompt+output as opt-in open training data.

================================================================================
AGENTS & MCP
================================================================================

Any MCP client (Claude Code, Cursor, opencode, Codex) can run every model.

1. Download the server:
   curl -o hero-run-mcp.mjs https://hero-run.vercel.app/hero-run-mcp.mjs
2. Install its one dependency:
   npm install viem
3. Get a key: mint one at https://hero-run.vercel.app/keys (connect a Base wallet, deposit $HERO).
4. Register with Claude Code:
   claude mcp add hero-run -e HERO_RUN_KEY=YOUR_KEY -- node /ABSOLUTE/PATH/hero-run-mcp.mjs

   Or any MCP client config:
   {
     "mcpServers": {
       "hero-run": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/hero-run-mcp.mjs"],
         "env": { "HERO_RUN_KEY": "YOUR_KEY" }
       }
     }
   }
5. Restart the client. The "hero-run" tools appear.

MCP tools:
  list_models(kind?)               list models + $HERO cost (free)
  run_text(prompt, model?)         text model (paid)
  generate_image(prompt, model?)   image (paid)
  treasury_stats()                 live fees funding open-source AI (free)
  wallet_balance()                 your $HERO + ETH (wallet mode)

================================================================================
PRICING & CREDITS
================================================================================

Pay per call in $HERO. Mint an API key at https://hero-run.vercel.app/keys by depositing $HERO once —
credits are 1:1 with your deposit and debit at each model's live $HERO price (no markup).
Or run wallet-mode (a Base wallet with $HERO + a little ETH) and pay per call with gas.

================================================================================
LINKS
================================================================================

Docs (web)     https://hero-run.vercel.app/docs
Mint a key     https://hero-run.vercel.app/keys
Model catalog  https://hero-run.vercel.app
MCP server     https://hero-run.vercel.app/hero-run-mcp.mjs
Agent setup    https://hero-run.vercel.app/llms.txt