Documentation
Quick start
# Python SDK pip install inferall-ai # TypeScript SDK npm install @inferall/sdk
Want a runnable example? examples/ in the repo has minimal Python and TypeScript scripts you can clone, edit, and run.
Base URL
https://api.inferall.aiAll requests require an API key via Authorization: Bearer ifu_... or x-api-key: ifu_... (legacy kr_proj_ keys are still accepted).
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /ai/v1/generate | Generate text, chat, images, or video |
| GET | /ai/v1/models | List all models with pricing |
| GET | /ai/v1/health | Health check |
| POST | /v1/messages | Anthropic-compatible (Claude Code) |
| POST | /ai/v1/keys | Create API key (requires JWT) |
| GET | /ai/v1/keys | List your keys (requires JWT) |
| GET | /ai/v1/usage | Usage summary (requires JWT) |
| GET | /ai/v1/key/status | Trial counter, balance, savings — auth via API key |
| POST | /ai/v1/billing/checkout | Stripe checkout session |
| GET | /ai/v1/billing/status | Billing status and spend |
Common errors
The gateway returns structured error messages that name the likely cause. Read the response body — the message field tells you exactly what to fix.
401 — wrong key prefix
If you point ANTHROPIC_BASE_URL/OPENAI_BASE_URL at InferAll but leave your existing provider key in place, the 401 message names the provider it came from:
- •
sk-...→ “looks like an OpenAI API key” - •
sk-ant-...→ “looks like an Anthropic API key” - •
sk-or-...→ “looks like an OpenRouter API key” - •
AIzaSy...→ “looks like a Google AI Studio key” - •
ifu_...but not in our DB → “key has an InferAll prefix but isn't in our database” (likely revoked or mistyped — mint a fresh one at /keys)
402 — billing required
Trial-eligible accounts (tier pending) need to complete the $5 starter-pack checkout at /billing to unlock free NIM-model access on 118+ models. The $5 becomes spendable balance — not a fee. Already activated and still seeing 402? Check that has_paid_successfully flipped after your charge cleared; if not, the webhook may have lagged — retry once and file support if it persists.
429 / 529 — rate limited
Honor Retry-After when present, otherwise exponential backoff. See /docs/rate-limits for the per-tier daily caps and per-operation limits.
TypeScript SDK
The native TypeScript SDK is live on npm as @inferall/sdk 0.1.0 (npm install @inferall/sdk). Prefer the official OpenAI or Anthropic SDK? Point either at the InferAll base URL — both work unchanged.
// Native TypeScript SDK — live on npm as @inferall/sdk 0.1.0
import { Inferall } from "@inferall/sdk";
const ai = new Inferall(); // reads INFERALL_API_KEY (ifu_...)
// Text (free OSS by default)
const text = await ai.text("Explain quantum computing in two sentences");
// Chat with a specific provider/model
const reply = await ai.chat(messages, {
provider: "anthropic",
model: "claude-sonnet-4-6",
});
// Vision
const analysis = await ai.vision(imageBase64, "What is this?");
// Image-to-video (Veo3) — pass a source frame for persona-consistency
const talkingHead = await ai.generate({
provider: "gemini",
model: "veo-3",
operation: "video-generate",
prompt: "Talking-head shot, looking at camera",
source_image_url: "https://example.com/persona-portrait.jpg",
});
// Prefer the official OpenAI/Anthropic SDKs instead? Point them at InferAll:
// OPENAI_BASE_URL=https://api.inferall.ai/v1 (key: ifu_...)
// ANTHROPIC_BASE_URL=https://api.inferall.ai (key: ifu_...)Python SDK
from inferall import Inferall
ai = Inferall() # reads INFERALL_API_KEY from the environment
# Text generation (free via NVIDIA Llama by default)
text = ai.text("Explain quantum computing")
# Chat with any provider
reply = ai.chat(messages, provider="anthropic", model="claude-sonnet-4-6")
# Vision
analysis = ai.vision(image_base64, "What is this?")
# Generate (image or video)
video = ai.generate(
provider="gemini",
model="veo-3.1-fast-generate-preview",
operation="video-generate",
prompt="Drone shot of a city",
)
# Image-to-video (Veo3) — pass a source frame to keep the subject consistent
talking_head = ai.generate(
provider="gemini",
model="veo-3",
operation="video-generate",
prompt="Talking-head shot, looking at camera",
source_image_url="https://example.com/persona-portrait.jpg",
)Claude Code integration
Point Claude Code (or any Anthropic-SDK app) at InferAll and the two env vars below are enough.
Default routing sends requests to free NVIDIA NIM open models at $0 input / $0 output. NIM access unlocks after the $5 starter pack settles; that same $5 becomes spendable balance for premium providers via the anthropic/claude-sonnet-4-6 style prefix.
# Use Claude Code with free inference export ANTHROPIC_BASE_URL=https://api.inferall.ai export ANTHROPIC_API_KEY=your_inferall_key # Run Claude Code normally — uses free NVIDIA models by default claude # Force a specific provider with model prefix # anthropic/claude-sonnet-4-6 → actual Claude # gemini/gemini-2.5-flash → Google Gemini
Key status (trial counter + savings)
GET /ai/v1/key/status — auth via your ifu_/kr_user_ API key (Bearer or x-api-key). Returns the trial counter, balance, and 7-day savings vs paid providers — enough for an SDK or CLI to render an upgrade nudge inline.
{
"tier": "pending",
"project": false,
"trial": { "used": 50, "remaining": 150, "cap": 200 },
"balance_cents": 500,
"balance_usd": 5,
"has_card": true,
"has_paid_successfully": true,
"savings_7d": {
"vs_gpt4o_mini_usd": 0.0318,
"vs_claude_sonnet_usd": 0.6373
},
"checkout_url": "https://inferall.ai/billing"
}For per-call awareness without an extra round-trip, every successful /v1/chat/completions from a trial key also includes X-InferAll-Trial-Usage: N/200 and X-InferAll-Trial-Status: active|halfway|near_cap response headers.
Providers
Live model list
View all available models with pricing at api.inferall.ai/ai/v1/models
More resources
Integrations — Claude Code, Cline, Cursor, LangChain, LlamaIndex, and more
Pricing — Free trial, Pro, Team, and Enterprise plans
Rate limits — Per-operation limits and spending caps