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 Required with an exact USDC quote; the caller pays on Base mainnet and retries with a PAYMENT-SIGNATURE header. 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 a Sign-In-With-X header on each paid call: base64(JSON {message, signature}) where message is an EIP-4361 text on domain livepairai.com with a fresh Issued 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. Read GET /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

EndpointAuthCost
GET /v1/agent/modelsnonefree — media catalog + textModels with retail $/Mtok (+ OpenAI object:"list" block)
GET /v1/agent/manifest.jsonnonefree — pricing model, guarantees, limits
GET /v1/agent/openapi.jsonnonefree — OpenAPI 3.1 for everything here
POST /v1/agent/quotenonefree — price a call first (live provider estimate)
POST /v1/agent/generatex402 or SIWX or keyper-call quote (media)
POST /v1/agent/chatx402 or SIWX or keytoken-metered (text)
POST /v1/agent/chat/completionsx402 or SIWX or keyOpenAI-shaped alias of /chat
POST /v1/agent/images/generationsx402 or SIWX or keyOpenAI Images API — {prompt, model, size, response_format} → {data:[{url}]}
POST /v1/agent/videosx402 or SIWX or keyOpenAI 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}nonefree — poll for the result URL
POST /v1/agent/x402/top-up?usd=Nx402 onlysettles N USDC (1–500, default 10) into the payer wallet's balance
GET /v1/agent/x402/balance/{wallet}nonefree — wallet balance in micro-USD
GET /v1/agent/x402/transactions/{wallet}nonefree — wallet ledger rows (topups, debits, refunds)
GET /v1/agent/balancekey onlyfree — prepaid balance + last 10 ledger entries
POST /v1/agent/referenceskey or SIWXfree — store a media reference ({media, label?} — media is a data URI or https URL, image ≤8MB / video ≤40MB) → {asset} with vectorReady
GET /v1/agent/referenceskey or SIWXfree — list your reference library (newest first, ≤100)
POST /v1/agent/references/searchoptionalfree — 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/packsnonefree — list curated moodboards (pack:<slug> + ref count)
DELETE /v1/agent/references/{id}key or SIWXfree — 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 idInputsWhat it does
image-face-swapimage + image2Swap the face from image2 (the reference) into image.
video-face-swapvideo + image2Same swap, applied across a source clip.
seedance-2.5-motionimage + video + promptSeedance 2.5 motion control — transfer the clip's motion onto the character image (480p/720p/1080p).
kling-3.0-motion / kling-3.0-pro-motionimage + video + promptKling 3.0 std/pro motion control.
dreamactor-v2image + videoDreamActor v2 — animate a character image from a reference clip.
pixverse-motionimage + videoPixVerse motion mimic (360p/540p/720p quality).
  • image2/video accept an https URL or a data: URI (image ≤8MB, video ≤40MB). Both swap inputs run the same vision policy check as image — 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 extra object, keyed by the setting names in each model's extraSettings (/api/gen/models, /v1/agent/models). e.g. extra: {quality: "720p"} on pixverse-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) accept extra: {loras: [{path, scale?}]} — 1–3 entries, path is an https URL to your .safetensors weights (CivitAI/HuggingFace/self-hosted), scale 0–4 default 1. The provider fetches the weights; no upload needed on our side. Wan video models also expose loraHighNoise/loraLowNoise for dual-stage control. Bring weights from anywhere — CivitAI, HuggingFace, or a trainer you ran elsewhere (upstream *-lora-trainer endpoints 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:

ModelInput $/MtokOutput $/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.

Loading interactive API reference…

Errors

StatusMeaning
400Bad request — unknown model, over a cap, or policy-blocked prompt. Never charged.
401Missing/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.
402x402: payment requirements to settle. Key/wallet rails: insufficient balance — body links topUp.
404Unknown job id (/jobs/{id}).
429Rate limit — 6/min generate, 30/min chat, per payer or key.
502/503Payment 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

PackageInstallWhat it is
livepairnpm i -g livepairTerminal CLI — livepair run/models/balance, installs an agent SKILL.md (guide)
@livepairai/n8n-nodes-livepairn8n community nodesImage/video generation inside n8n workflows (guide)
livepair-botscloneDiscord/Telegram/X bot templates (zero-dependency Node)
ComfyUI-LivePairComfyUI ManagerComfyUI custom nodes
livepair-skillslivepair skill installAgent 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.