API reference
The Agent API exposes image generation, video generation, and LLM chat completions to scripts and autonomous agents. Every paid call settles one of three ways — pick per call:
-
x402 — no account, no key. The call returns
402 Payment Requiredwith an exact USDC quote; the caller pays on Base mainnet and retries with aPAYMENT-SIGNATUREheader. Built for agents holding a wallet. -
Wallet balance — fund once via
POST /v1/agent/x402/top-up(pays with x402, credits your wallet address), then send aSign-In-With-Xheader on each paid call:base64(JSON {message, signature})wheremessageis an EIP-4361 text on domainlivepairai.comwith a freshIssued At(≤5 min) signed by the funded wallet. No per-call on-chain tx, and a provider-side failure refunds the balance — the rail repeat agents should use. ReadGET /v1/agent/x402/balance/{wallet}. -
lp_API key — sign up, top up credits at /billing, create a key in Settings, and send it on every call. The same prepaid balance powers the studio and agent chat. See API keys. -
Base URL:
https://livepairai.com/v1/agent -
OpenAPI 3.1:
/v1/agent/openapi.json -
Product manifest:
/v1/agent/manifest.json -
Machine guide:
/SKILL.md· MCP:https://livepairai.com/mcp(guide)
Charges apply only when a call succeeds: 4xx/5xx responses are never
settled on x402, and on the wallet/key rails a provider-side failure
auto-refunds the debit. POST /v1/agent/quote prices any call for free
before you pay — same live provider estimate the billing uses.
Quick start
With an API key (credits)
curl https://livepairai.com/v1/agent/chat \
-H "Authorization: Bearer lp_your_key" \
-H "Content-Type: application/json" \
-d '{
"model": "{DEFAULT_TEXT_MODEL}",
"messages": [{"role": "user", "content": "Say hi in one sentence."}],
"max_tokens": 64
}'
With x402 (no account)
# 1. First call returns 402 with exact USDC requirements
curl -X POST https://livepairai.com/v1/agent/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "a lighthouse at dawn, film still"}'
# 2. Pay the quoted amount on Base (USDC), then retry with the proof
curl -X POST https://livepairai.com/v1/agent/generate \
-H "Content-Type: application/json" \
-H "PAYMENT-SIGNATURE: <settlement payload>" \
-d '{"prompt": "a lighthouse at dawn, film still"}'
# → { "jobId": "…" } — poll GET /v1/agent/jobs/{jobId} for the result URL
Volume tiers apply wallet-keyed on the x402 and wallet rails — 5% at $100+, 10% at $500+, 15% at $2000+. Keys bill list price.
Endpoints
| Endpoint | Auth | Cost |
|---|---|---|
GET /v1/agent/models | none | free — media catalog + textModels with retail $/Mtok (+ OpenAI object:"list" block) |
GET /v1/agent/manifest.json | none | free — pricing model, guarantees, limits |
GET /v1/agent/openapi.json | none | free — OpenAPI 3.1 for everything here |
POST /v1/agent/quote | none | free — price a call first (live provider estimate) |
POST /v1/agent/generate | x402 or SIWX or key | per-call quote (media) |
POST /v1/agent/chat | x402 or SIWX or key | token-metered (text) |
POST /v1/agent/chat/completions | x402 or SIWX or key | OpenAI-shaped alias of /chat |
POST /v1/agent/images/generations | x402 or SIWX or key | OpenAI Images API — {prompt, model, size, response_format} → {data:[{url}]} |
POST /v1/agent/videos | x402 or SIWX or key | OpenAI Videos API (Sora) — job object; GET /v1/agent/videos/{id} polls, GET /v1/agent/videos/{id}/content fetches the mp4 |
GET /v1/agent/jobs/{id} | none | free — poll for the result URL |
POST /v1/agent/x402/top-up?usd=N | x402 only | settles N USDC (1–500, default 10) into the payer wallet's balance |
GET /v1/agent/x402/balance/{wallet} | none | free — wallet balance in micro-USD |
GET /v1/agent/x402/transactions/{wallet} | none | free — wallet ledger rows (topups, debits, refunds) |
GET /v1/agent/balance | key only | free — prepaid balance + last 10 ledger entries |
POST /v1/agent/references | key or SIWX | free — store a media reference ({media, label?} — media is a data URI or https URL, image ≤8MB / video ≤40MB) → {asset} with vectorReady |
GET /v1/agent/references | key or SIWX | free — list your reference library (newest first, ≤100) |
POST /v1/agent/references/search | optional | free — semantic search {query, k?, pack?} over your library and shared curated packs — pack scopes to one moodboard (authed = both, unauth = packs only) → ranked candidates, attaches nothing |
GET /v1/agent/references/packs | none | free — list curated moodboards (pack:<slug> + ref count) |
DELETE /v1/agent/references/{id} | key or SIWX | free — remove the row, vector, and blob |
Reference library (media RAG)
POST /v1/agent/references stores an image or clip in a per-caller library.
On upload we embed it with a multimodal model into a vector namespace
keyed by your auth identity (u:<userId> for keys/sessions, w:<0x…> for
SIWX wallets) — the namespace is the tenant boundary, so retrieval can never
see another caller's refs.
Attach them at generation time on /v1/agent/generate (and /api/gen):
"useReferences": true— embeds your prompt and attaches the top matches to the model's empty media inputs (image-kind →image/image2, video-kind →video). Inputs you pass explicitly always win."referenceIds": ["<id>", …]— pin exact refs in order (≤4).
POST /v1/agent/references/search {query, k?, pack?} is the conversational
path: it ranks candidates across your library and the shared
pack:<slug> namespaces without attaching anything — an agent or copilot
shows the hits, the caller picks, and the chosen ids go into
referenceIds. Pass "pack": "<slug>" to search inside a single
moodboard — the flow for an agent is GET …/packs → pick the moodboard
that fits → scoped search → pin winners.
Shared packs are curated moodboards (cohesive lighting/grade/mood sets —
golden-hour, neon-night, noir-bw…) — readable by every caller, writable
only by us, and listed via GET /v1/agent/references/packs. Pinning a
pack ref works from any account.
Attached refs then ride the identical fetch → vision policy check →
provider-upload pipeline as direct media inputs, so policy is not bypassed
by the library path. Anonymous per-call x402 callers have no library — use
an lp_ key or the SIWX wallet rail. The same three endpoints are also
mounted at /api/references for the studio's session surface (session
cookie or lp_ key). vectorReady: false on an asset means
embedding failed or the clip exceeded the inline-embed limit — still
attachable by id, just not semantically searchable.
Specialist media models (multi-input)
The public catalog includes face-swap, motion-control, and
character-animation models that take two inputs — they're listed on
/models, selectable in the studio (the composer collects a target image
plus a face, or a subject image plus a motion clip), and callable over both
POST /api/gen and POST /v1/agent/generate:
| Model id | Inputs | What it does |
|---|---|---|
image-face-swap | image + image2 | Swap the face from image2 (the reference) into image. |
video-face-swap | video + image2 | Same swap, applied across a source clip. |
seedance-2.5-motion | image + video + prompt | Seedance 2.5 motion control — transfer the clip's motion onto the character image (480p/720p/1080p). |
kling-3.0-motion / kling-3.0-pro-motion | image + video + prompt | Kling 3.0 std/pro motion control. |
dreamactor-v2 | image + video | DreamActor v2 — animate a character image from a reference clip. |
pixverse-motion | image + video | PixVerse motion mimic (360p/540p/720p quality). |
image2/videoaccept an https URL or adata:URI (image ≤8MB, video ≤40MB). Both swap inputs run the same vision policy check asimage— apparent minors are refused outright; use only faces you have the right to use.- Video-input jobs are priced on the measured source duration via the provider's official estimate — the catalog's listed price is the reference-clip quote; each call is re-quoted against its actual input before billing.
- Model-specific knobs ride the
extraobject, keyed by the setting names in each model'sextraSettings(/api/gen/models,/v1/agent/models). e.g.extra: {quality: "720p"}onpixverse-motion,extra: {characterOrientation: "image", keepOriginalSound: false}on the Kling motion models,extra: {targetGender: "female", targetIndex: 0}on the face swaps. Unknown keys or out-of-range values are rejected with 400; settings you omit fall back to the provider default. - BYO LoRA — lora-capable models (
flux-dev-lora,flux-kontext-lora,qwen-image-2.1-lora,wan-2.2-i2v-lora,wan-2.2-t2v-lora,wan-2.2-private-i2v-lora) acceptextra: {loras: [{path, scale?}]}— 1–3 entries,pathis an https URL to your.safetensorsweights (CivitAI/HuggingFace/self-hosted),scale0–4 default 1. The provider fetches the weights; no upload needed on our side. Wan video models also exposeloraHighNoise/loraLowNoisefor dual-stage control. Bring weights from anywhere — CivitAI, HuggingFace, or a trainer you ran elsewhere (upstream*-lora-trainerendpoints exist; a hosted train-your-own surface may land here later).
Text models and pricing
GET /v1/agent/models returns textModels with these retail rates —
this table renders from the same catalog, so the numbers can't drift:
| Model | Input $/Mtok | Output $/Mtok |
|---|---|---|
openai/gpt-6-luna — GPT-6 Luna | $0.15 | $0.77 |
z-ai/glm-5.3-flash — GLM 5.3 Flash | $0.23 | $0.77 |
google/gemini-3.5-flash-lite — Gemini 3.5 Flash Lite | $0.46 | $3.85 |
meta-llama/llama-3.3-70b-instruct — Llama 3.3 70B — open weights | $1.11 | $1.11 |
anthropic/claude-sonnet-5.5 — Claude Sonnet 5.5 — frontier | $3.08 | $15.38 |
deepseek/deepseek-v4.1-flash — DeepSeek 4.1 Flash | $0.23 | $0.92 |
qwen/qwen3.7-plus — Qwen3.7 Plus | $0.49 | $1.97 |
moonshotai/kimi-k3 — Kimi K3 | $4.62 | $23.08 |
x-ai/grok-4.20 — Grok 4.20 | $1.92 | $3.85 |
anthropic/claude-opus-5.5 — Claude Opus 5.5 | $6.15 | $30.77 |
anthropic/claude-fable-5.1 — Claude Fable 5.1 | $15.38 | $76.92 |
anthropic/claude-haiku-4.5 — Claude Haiku 4.5 | $1.54 | $7.69 |
deepseek/deepseek-r1 — DeepSeek R1 — reasoning | $1.08 | $3.85 |
google/gemini-3.8-flash — Gemini 3.8 Flash | $2.31 | $11.54 |
google/gemini-3-flash-preview — Gemini 3 Flash Preview | $0.77 | $4.62 |
google/gemma-4-31b-it — Gemma 4 31B — open weights | $0.23 | $0.62 |
google/gemma-4-26b-a4b-it — Gemma 4 26B A4B — open weights | $0.12 | $0.49 |
minimax/minimax-m3 — MiniMax M3 | $0.46 | $1.85 |
mistralai/mistral-large — Mistral Large | $3.08 | $9.23 |
mistralai/mistral-nemo — Mistral Nemo | $0.23 | $0.23 |
moonshotai/kimi-k2.7-code — Kimi K2.7 Code | $1.46 | $6.15 |
openai/gpt-6.1-sol — GPT-6.1 Sol | $3.08 | $15.38 |
openai/gpt-6-astra — GPT-6 Astra | $15.38 | $76.92 |
openai/gpt-5.6-terra — GPT-5.6 Terra | $3.08 | $18.46 |
openai/gpt-5.5 — GPT-5.5 | $7.69 | $46.15 |
openai/gpt-5.4-mini — GPT-5.4 Mini | $1.15 | $6.92 |
openai/gpt-5.4-nano — GPT-5.4 Nano | $0.31 | $1.92 |
openai/gpt-5.3-codex — GPT-5.3 Codex | $2.69 | $21.54 |
openai/gpt-oss-120b — GPT-OSS 120B — open weights | $0.23 | $0.92 |
qwen/qwen3.8-flash — Qwen3.8 Flash | $0.23 | $0.72 |
qwen/qwen3.7-max — Qwen3.7 Max | $2.27 | $6.81 |
qwen/qwen3-coder-next — Qwen3 Coder Next | $0.46 | $2.31 |
z-ai/glm-5.3 — GLM 5.3 | $2.15 | $6.77 |
Chat price is computed per call from the body: estimated input tokens
(ceil(totalChars / 3.5)) at the input rate plus max_tokens at the
output rate, with a $0.002 floor. Bill
tighter by setting max_tokens tight — you pay for the cap, not the
actual completion length. Default model: {DEFAULT_TEXT_MODEL}.
Interactive reference
Rendered live from /v1/agent/openapi.json —
request/response schemas, auth, and per-endpoint notes always match the
running API. Try calls directly from the console below.
Errors
| Status | Meaning |
|---|---|
400 | Bad request — unknown model, over a cap, or policy-blocked prompt. Never charged. |
401 | Missing/invalid lp_ key (KEY_NOT_FOUND, KEY_EXPIRED, disabled, or banned account) or rejected Sign-In-With-X (stale, wrong_domain, bad_signature). Body links manageKeys/howToAuth. |
402 | x402: payment requirements to settle. Key/wallet rails: insufficient balance — body links topUp. |
404 | Unknown job id (/jobs/{id}). |
429 | Rate limit — 6/min generate, 30/min chat, per payer or key. |
502/503 | Payment verification or provider temporarily unavailable — never settled / auto-refunded. |
Guarantees and limits
- Failed calls don't charge. x402 settles only on success status; key and wallet debits auto-refund on provider failure.
- Resale permitted — outputs may be resold.
- Geo: generation is unavailable in sanctioned regions; the catalog
marks the private model line with
"private": true. - Key safety: keys spend your balance — server-side only, never in a browser bundle or repo. Manage at Settings → API keys.
Packages & clients
| Package | Install | What it is |
|---|---|---|
livepair | npm i -g livepair | Terminal CLI — livepair run/models/balance, installs an agent SKILL.md (guide) |
@livepairai/n8n-nodes-livepair | n8n community nodes | Image/video generation inside n8n workflows (guide) |
| livepair-bots | clone | Discord/Telegram/X bot templates (zero-dependency Node) |
| ComfyUI-LivePair | ComfyUI Manager | ComfyUI custom nodes |
| livepair-skills | livepair skill install | Agent SKILL.md source |
Apps that already speak OpenAI — SillyTavern, Open WebUI, new-api, Cherry Studio, LibreChat — plug in by base URL alone; see OpenAI-compatible apps.