{"openapi":"3.1.0","info":{"title":"Private AI Media Generation API","version":"1.1.0","description":"Pay-per-call AI image and video generation for autonomous agents — including a private model line — plus private LLM text completions. Three payment rails: x402 (no account — the request settles in USDC on Base via HTTP 402), a prepaid wallet balance funded via POST /v1/agent/x402/top-up and spent per call with a Sign-In-With-X signature (recommended for repeat agents — no per-call on-chain tx, failures refund to the balance), or an account API key (`x-api-key: lp_…` / `Authorization: Bearer lp_…`, bills prepaid credits). Charges apply only when the call succeeds (4xx/5xx responses are never settled / are auto-refunded). Wallet-keyed volume discounts (5% at $100+, 10% at $500+, 15% at $2000+) apply on the x402 and wallet rails; resale of outputs is permitted.","x-guidance":"Use POST /v1/agent/generate to render images or videos, POST /v1/agent/chat for OpenAI-compatible text completions ({model, messages, max_tokens}). Pass 'modelId'/'model' (from GET /v1/agent/models) and optional settings; include 'payer' (your 0x wallet) for volume-tier pricing. The 402 response carries exact per-call USDC requirements — or send an lp_ API key and the same call bills the owner's prepaid credits with no 402 round-trip — or POST /v1/agent/x402/top-up?usd=N once, then sign EIP-4361 messages (domain livepairai.com) and send `Sign-In-With-X` to debit your wallet balance per call. POST /v1/agent/quote prices any call for free.","contact":{"email":"tristayunsub@gmail.com"}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Account API key (lp_…) — create at https://livepairai.com/settings after signing up at /auth/sign-up. Bills the key owner's prepaid credit balance."},"BearerKey":{"type":"http","scheme":"bearer","description":"Same lp_ API key as a Bearer token."},"SiwxHeader":{"type":"apiKey","in":"header","name":"Sign-In-With-X","description":"Wallet rail auth — base64(JSON {message, signature}) where message is an EIP-4361 text on domain livepairai.com with Issued At within 5 minutes, signed by the wallet holding a prepaid balance (fund via POST /v1/agent/x402/top-up)."}}},"paths":{"/v1/agent/models":{"get":{"operationId":"list_models","summary":"List agent-available models and per-call USD prices","security":[],"responses":{"200":{"description":"Model catalog","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object"}}}}}}}}}},"/v1/agent/balance":{"get":{"operationId":"get_balance","summary":"Prepaid credit balance and recent ledger for the lp_ key owner (x402 wallets are anonymous — key required)","security":[{"ApiKeyHeader":[]},{"BearerKey":[]}],"responses":{"200":{"description":"Balance in micro-USD plus the 10 most recent credit transactions","content":{"application/json":{"schema":{"type":"object","properties":{"balanceUsd":{"type":"number"},"balanceMicro":{"type":"integer"},"currency":{"type":"string"},"recent":{"type":"array","items":{"type":"object"}},"topUp":{"type":"string"}}}}}},"401":{"description":"Missing or invalid lp_ API key"}}}},"/v1/agent/x402/top-up":{"post":{"operationId":"wallet_top_up","summary":"Fund the prepaid wallet balance — x402 settles USDC into the payer wallet's balance (query param usd=N, 1–500, default 10). Spend it per call with a Sign-In-With-X header instead of per-call payment.","security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD"},"protocols":[{"x402":{}}]},"parameters":[{"name":"usd","in":"query","schema":{"type":"number","minimum":1,"maximum":500},"description":"Top-up amount in USD — clamped to 1–500, default 10"}],"responses":{"200":{"description":"Payment settled and credited — wallet, topUpMicro, balanceMicro"},"402":{"description":"Payment required"}}}},"/v1/agent/x402/balance/{wallet}":{"get":{"operationId":"wallet_balance","summary":"Prepaid wallet balance (micro-USD)","security":[],"parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"{ wallet, balanceMicro }"},"400":{"description":"Invalid wallet address"}}}},"/v1/agent/x402/transactions/{wallet}":{"get":{"operationId":"wallet_transactions","summary":"Recent wallet ledger rows (topups, debits, refunds)","security":[],"parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"{ wallet, transactions[] }"},"400":{"description":"Invalid wallet address"}}}},"/v1/agent/references":{"get":{"operationId":"references_list","summary":"List your media-reference library — scoped to the authenticated key or wallet","responses":{"200":{"description":"{ refs[] } — id, kind, mime, bytes, label, url, vectorReady"},"401":{"description":"No valid auth (x-api-key lp_… or Sign-In-With-X)"}}},"post":{"operationId":"references_create","summary":"Store a reference image/video — embedded into your private vector namespace for useReferences retrieval","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["media"],"properties":{"media":{"type":"string","description":"data:image|video URI, or a public https URL"},"label":{"type":"string","description":"optional caption (≤200 chars)"}}}}}},"responses":{"201":{"description":"{ ok, asset } — vectorReady=1 means semantically searchable"},"400":{"description":"Missing/oversized media (image ≤8MB, video ≤40MB)"},"415":{"description":"Only image/* or video/* references"},"422":{"description":"Vision policy rejection"},"429":{"description":"Library full (100 per owner) or rate limited"}}}},"/v1/agent/references/{id}":{"delete":{"operationId":"references_delete","summary":"Delete a reference — removes the row, the vector, and the blob","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ ok: true }"},"404":{"description":"Not found (or not yours)"}}}},"/v1/agent/quote":{"post":{"operationId":"quote","summary":"Free public price check — same live provider estimate the billing uses","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["modelId"],"properties":{"modelId":{"type":"string"},"model":{"type":"string"},"prompt":{"type":"string"},"duration":{"type":"number"},"resolution":{"type":"string"},"imageSize":{"type":"string"},"messages":{"type":"array","items":{"type":"object"}},"max_tokens":{"type":"integer"}}}}}},"responses":{"200":{"description":"{ modelId, mode, priceMicro, providerCostMicro?, live } — priceMicro is the exact charge for that input"},"404":{"description":"Unknown model"}}}},"/v1/agent/generate":{"post":{"operationId":"generate_media","summary":"Generate an image or video (x402 or API-key paid)","security":[{"ApiKeyHeader":[]},{"BearerKey":[]},{}],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.004546","max":"83.076924"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":2000},"modelId":{"type":"string","description":"model id from /v1/agent/models"},"image":{"type":"string","description":"Source image for i2i/i2v models — public http(s) URL or data:image URI (<=8MB). Use AI-generated or owned images only, never real-person photos without consent. Screened by the same policy check as the studio."},"image2":{"type":"string","description":"Face/subject reference image for swap models — same rules as `image`."},"video":{"type":"string","description":"Source clip for motion-control / video-input models — https URL or data:video URI (<=40MB)."},"useReferences":{"type":"boolean","description":"Embed the prompt and attach top matches from your reference library (POST /v1/agent/references) to the model's empty media inputs — lp_ key or SIWX wallet required."},"referenceIds":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Pin exact reference ids to the model's empty media inputs (image→image/image2, video→video)."},"imageSize":{"type":"string"},"aspectRatio":{"type":"string"},"duration":{"type":"number","description":"Video length in seconds — billed per second at the model's per-resolution rate"},"resolution":{"type":"string"},"audio":{"type":"boolean","description":"Audio track on audio-capable video models (default on)"},"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Your payer wallet — applies your volume-tier discount to the 402 quote (5% at $100+, 10% at $500+, 15% at $2000+ lifetime paid). Must equal the wallet that signs the payment."}}}}}},"responses":{"200":{"description":"{status:'done',url} or {status:'running',jobId,poll} — payment settles on submit","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","running"]},"url":{"type":"string"},"jobId":{"type":"string"},"poll":{"type":"string"}},"required":["status"]}}}},"402":{"description":"Payment Required — PAYMENT-REQUIRED header carries accepts[] requirements (USDC on Base eip155:8453)"}}}},"/v1/agent/chat":{"post":{"operationId":"chat_completions","summary":"Private LLM chat completion (x402 or API-key paid)","security":[{"ApiKeyHeader":[]},{"BearerKey":[]},{}],"description":"OpenAI-compatible chat completion — pass an OpenAI-style {model, messages, max_tokens} body, receive the standard {choices, usage} response. Price is per call: ceil(total message chars / 3.5) estimated input tokens × the model's input rate + max_tokens × its output rate, marked up — set max_tokens tight for tighter billing. Anonymous — no account; metering keeps token counts only.","x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.002000","max":"0.841144"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"model":{"type":"string","description":"Text model id — see textModels in GET /v1/agent/models (default: deepseek/deepseek-v4-flash)"},"messages":{"type":"array","maxItems":50,"description":"OpenAI chat messages — role system|user|assistant, string content, <=48000 chars total","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"max_tokens":{"type":"number","maximum":8192,"default":1024,"description":"Output token cap — billed at this amount; set it tight to pay less"},"temperature":{"type":"number","minimum":0,"maximum":2},"reasoning_effort":{"type":"string","enum":["low","medium","high"],"description":"OpenAI-style reasoning effort — passed through to reasoning-capable models"},"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Your payer wallet — applies your volume-tier discount (5% at $100+, 10% at $500+, 15% at $2000+ lifetime paid). Must equal the wallet that signs the payment."}}}}}},"responses":{"200":{"description":"OpenAI chat completion — {choices:[{message:{role,content}}], usage:{prompt_tokens,completion_tokens}}","content":{"application/json":{"schema":{"type":"object","properties":{"choices":{"type":"array","items":{"type":"object"}},"usage":{"type":"object"}}}}}},"402":{"description":"Payment Required — PAYMENT-REQUIRED header carries accepts[] requirements (USDC on Base eip155:8453)"}}}},"/v1/agent/images/generations":{"post":{"operationId":"images_generations","summary":"OpenAI-compatible text-to-image (x402 or API-key paid)","security":[{"ApiKeyHeader":[]},{"BearerKey":[]},{}],"description":"OpenAI Images API shape — point an OpenAI-compatible client at this base URL and image generation works unmodified. `model` accepts LivePair image model ids (see models in GET /v1/agent/models); unknown ids return 400 rather than silently swapping models. `size` maps to aspect ratio (1024x1024→1:1, 1792x1024→16:9, 1024x1792→9:16); LivePair extension fields aspectRatio/resolution/imageSize are honored when the model advertises them. Synchronous up to ~100s — past that the response is the standard {status:'running',jobId,poll} handoff; a submitted job that fails later provider-side is not un-charged.","x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.004546","max":"83.076924"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Image prompt, <=2000 chars"},"model":{"type":"string","description":"LivePair image model id — omit for the catalog default (qwen-image-3)"},"size":{"type":"string","enum":["1024x1024","1792x1024","1024x1792","1536x1024","1024x1536"]},"n":{"type":"number","description":"Only 1 supported"},"response_format":{"type":"string","enum":["url","b64_json"],"default":"url"},"aspectRatio":{"type":"string"},"resolution":{"type":"string"},"imageSize":{"type":"string"},"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Your payer wallet — applies your volume-tier discount (5% at $100+, 10% at $500+, 15% at $2000+ lifetime paid). Must equal the wallet that signs the payment."}}}}}},"responses":{"200":{"description":"OpenAI images response — {created, data:[{url} | {b64_json}]} (or {status:'running',jobId,poll} past the sync window)","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"number"},"data":{"type":"array","items":{"type":"object"}}}}}}},"402":{"description":"Payment Required — PAYMENT-REQUIRED header carries accepts[] requirements (USDC on Base eip155:8453)"}}}},"/v1/agent/videos":{"post":{"operationId":"videos_create","summary":"OpenAI-compatible text-to-video (Sora shape; x402 or API-key paid)","security":[{"ApiKeyHeader":[]},{"BearerKey":[]},{}],"description":"OpenAI Videos API shape — returns a job object immediately; poll GET /v1/agent/videos/{id} for status, fetch the mp4 at GET /v1/agent/videos/{id}/content (302 to the media URL). `model` accepts LivePair video model ids (mode t2v in the catalog); `size` maps to aspect ratio + resolution tier (1280x720→16:9/720p, 720x1280→9:16/720p, 1792 edges→1080p); `seconds` maps to the model's duration ladder. The payment settles at submit — a provider-side failure discovered later refunds the API-key rail via the sweep (x402 settlement cannot un-settle).","x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.004546","max":"83.076924"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"model":{"type":"string","description":"LivePair video model id — omit for the catalog default"},"size":{"type":"string","enum":["1280x720","720x1280","1792x1024","1024x1792"]},"seconds":{"type":"string"},"resolution":{"type":"string"},"aspectRatio":{"type":"string"},"audio":{"type":"boolean"},"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}}}}},"responses":{"200":{"description":"Sora-shaped video job — {id, object:'video', status, model, size, seconds, created_at}"},"402":{"description":"Payment Required — PAYMENT-REQUIRED header carries accepts[] requirements (USDC on Base eip155:8453)"}}}},"/v1/agent/jobs/{id}":{"get":{"operationId":"get_job","summary":"Poll a running generation job (free)","security":[],"responses":{"200":{"description":"{status:'done',url} | {status:'running'} | {status:'failed'}","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"url":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}