{ "openapi": "3.1.0", "info": { "title": "CheapTokens API", "version": "1.0.0", "description": "Machine-readable API for discovering CheapTokens pricing/supply, choosing x402 or card checkout routes, purchasing discounted Venice.ai API credits, inspecting Same-Day and Prepaid API Key status, recovering card-purchased keys through private email links, managing wallet-owned keys, and testing keys in the browser Playground." }, "servers": [ { "url": "https://cheaptokens.ai", "description": "Production" } ], "tags": [ { "name": "discovery", "description": "Pricing, supply, checkout options, and Venice model catalog discovery" }, { "name": "purchase", "description": "x402 and card checkout flows for Same-Day Credits and Prepaid API Keys" }, { "name": "status", "description": "Inspect purchased key status without exposing full bearer keys" }, { "name": "card-recovery", "description": "Private email-link recovery/account flows for Stripe card buyers" }, { "name": "wallet", "description": "Wallet-authenticated purchase recovery and key management" }, { "name": "playground", "description": "Browser Playground proxy endpoints for testing CheapTokens/Venice keys" } ], "paths": { "/api/pricing": { "get": { "tags": [ "discovery" ], "summary": "Get current CheapTokens pricing state", "description": "Returns the current UTC time-based discount, effective credits per dollar, and supply snapshot for a given UTC date. This is the server-authoritative source of truth for displayed CheapTokens discount values. Capacity affects availability and maximum purchase size, not price.", "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Optional UTC date in YYYY-MM-DD format. Defaults to today UTC." } ], "responses": { "200": { "description": "Current pricing state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } }, "400": { "description": "Invalid date" }, "500": { "description": "Pricing fetch failed" } } } }, "/api/supply": { "get": { "tags": [ "discovery" ], "summary": "Get current supply status", "description": "Returns daily CheapTokens capacity, sold/remaining amounts, sold-out state, reset timing, and purchase constraints. Use ?date=YYYY-MM-DD to check whether a Prepaid daily reserve fits the unreserved capacity for that UTC day.", "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Optional UTC date in YYYY-MM-DD format. Defaults to today UTC." } ], "responses": { "200": { "description": "Supply status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplyResponse" } } } }, "400": { "description": "Invalid date" }, "500": { "description": "Supply fetch failed" }, "503": { "description": "Supply temporarily unavailable" } } } }, "/api/buy": { "post": { "tags": [ "purchase" ], "summary": "Purchase discounted Venice.ai credits via x402", "description": "Programmatic x402 purchase endpoint. Initial unsigned request returns HTTP 402 with payment requirements. Retry with a signed x402 payment header to complete a Same-Day Credit purchase, create a Prepaid API Key, or top up a wallet-owned active Prepaid API Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyRequest" } } } }, "responses": { "200": { "description": "Purchase completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuySuccessResponse" } } } }, "402": { "description": "Payment required or payment invalid. Initial response carries x402 payment requirements.", "headers": { "X-PAYMENT-REQUIRED": { "description": "x402 payment requirements payload for the requested purchase", "schema": { "type": "string" } } } }, "409": { "description": "Conflict, sold out, or session mismatch" }, "429": { "description": "Rate limited" }, "503": { "description": "Payments or supply temporarily unavailable" } } } }, "/api/status/{keyPrefix}": { "get": { "tags": [ "status" ], "summary": "Inspect purchase/key status by last 6+ characters", "description": "Returns limited status information for a purchased Venice key by its last 6 or more characters. Designed for safe programmatic monitoring without full key disclosure.", "parameters": [ { "name": "keyPrefix", "in": "path", "required": true, "schema": { "type": "string", "minLength": 6 }, "description": "Last 6 or more characters of a Venice key issued by CheapTokens." } ], "responses": { "200": { "description": "Purchase status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "400": { "description": "Key prefix too short" }, "404": { "description": "Purchase not found" }, "429": { "description": "Rate limited" }, "500": { "description": "Status fetch failed" } } } }, "/api/venice/pricing": { "get": { "tags": [ "discovery" ], "summary": "Get live Venice text model pricing", "description": "Returns the live Venice model pricing table parsed from official Venice docs. Currently scoped to the primary text/chat pricing table.", "responses": { "200": { "description": "Live Venice pricing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenicePricingResponse" } } } }, "502": { "description": "Failed to fetch Venice pricing" } } } }, "/api/wallet/purchases": { "post": { "tags": [ "wallet" ], "summary": "List purchases for a verified wallet", "description": "Returns recent purchases for a wallet after verifying signed wallet authentication with replay protection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAuthRequest" } } } }, "responses": { "200": { "description": "Purchases list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPurchasesResponse" } } } }, "401": { "description": "Authentication failed" }, "500": { "description": "Failed to fetch purchases" } } } }, "/api/wallet/reveal": { "post": { "tags": [ "wallet" ], "summary": "Reveal full Venice key for a verified purchase", "description": "Reveals the full stored Venice API key for a purchase after wallet-authenticated ownership verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletAuthRequest" }, { "type": "object", "required": [ "purchaseId" ], "properties": { "purchaseId": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Full Venice API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "veniceApiKey" ], "properties": { "veniceApiKey": { "type": "string" } } } } } }, "401": { "description": "Authentication failed" }, "403": { "description": "Wallet does not own purchase" }, "404": { "description": "Purchase or key not found" }, "429": { "description": "Rate limited" }, "500": { "description": "Reveal failed" } } } }, "/api/wallet/reissue": { "post": { "tags": [ "wallet" ], "summary": "Reissue a Venice key for a verified active purchase", "description": "Deletes the previous Venice key if possible and creates a fresh one for an active purchase after wallet-authenticated ownership verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletAuthRequest" }, { "type": "object", "required": [ "purchaseId" ], "properties": { "purchaseId": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Reissued Venice API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "veniceApiKey", "veniceKeyLast6", "purchase" ], "properties": { "success": { "type": "boolean" }, "veniceApiKey": { "type": "string" }, "veniceKeyLast6": { "type": "string" }, "purchase": { "type": "object", "properties": { "id": { "type": "string" }, "creditsIssuedUsd": { "type": [ "number", "string" ] }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Authentication failed" }, "403": { "description": "Wallet does not own purchase" }, "404": { "description": "Purchase not found" }, "429": { "description": "Rate limited" }, "500": { "description": "Reissue failed" } } } }, "/api/checkout/options": { "get": { "tags": [ "discovery" ], "summary": "Discover checkout routes and product availability", "description": "Returns the currently available checkout routes, recommended agent route, UTC reset timing, and Prepaid API Key availability. Agents should use this before deciding between x402, card checkout, Same-Day Credits, or Prepaid API Key.", "parameters": [ { "name": "amountUsd", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Optional intended purchase amount for route context." }, { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Optional UTC date hint. Defaults to today UTC." }, { "name": "dates", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "style": "form", "explode": true, "description": "Optional legacy date hints for compatibility." } ], "responses": { "200": { "description": "Checkout options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutOptionsResponse" } } } }, "500": { "description": "Checkout options fetch failed" } } } }, "/api/stripe/checkout": { "post": { "tags": [ "purchase" ], "summary": "Create a Stripe card checkout session", "description": "Browser-oriented card checkout for Same-Day Credits and initial Prepaid API Key purchases. Card top-ups for existing keys are not available; use Base USDC/x402 for Account top-ups.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutRequest" } } } }, "responses": { "200": { "description": "Stripe checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutResponse" } } } }, "400": { "description": "Invalid amount, product mode, or unsupported card top-up" }, "409": { "description": "Capacity, cutoff, or card rebalance cap conflict" }, "429": { "description": "Rate limited" }, "503": { "description": "Card checkout disabled or unavailable" } } } }, "/api/stripe/order": { "get": { "tags": [ "purchase" ], "summary": "Claim same-browser Stripe checkout result", "description": "Returns card order status and reveals the full key only when the caller has the same-browser checkout claim cookie. For later recovery, use the private email-link flow.", "parameters": [ { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Stripe Checkout Session id." } ], "responses": { "200": { "description": "Card order status or claimed key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeOrderResponse" } } } }, "400": { "description": "Missing session id" }, "403": { "description": "Missing or invalid same-browser claim cookie" }, "404": { "description": "Card order not found" }, "410": { "description": "Same-browser claim window expired" } } } }, "/api/stripe/recover": { "post": { "tags": [ "card-recovery" ], "summary": "Request a private card account/recovery link", "description": "Accepts the Stripe receipt or Stripe Link checkout email and always returns a generic response. If fulfilled card purchases exist, CheapTokens emails a private one-time Account link. The public form does not reveal whether the email has purchases.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeRecoverRequest" } } } }, "responses": { "200": { "description": "Generic non-enumerating response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeRecoverResponse" } } } }, "400": { "description": "Invalid email" }, "429": { "description": "Rate limited" } } } }, "/api/stripe/recover/claim": { "post": { "tags": [ "card-recovery" ], "summary": "Claim a one-time card account/recovery token", "description": "Consumes a private email recovery token and returns the matching card-purchased keys plus account summary rows. Tokens are one-time and expire quickly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeRecoverClaimRequest" } } } }, "responses": { "200": { "description": "Recovered card keys and account summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeRecoverClaimResponse" } } } }, "400": { "description": "Invalid token shape" }, "410": { "description": "Recovery link expired or already used" }, "429": { "description": "Rate limited" } } } }, "/api/playground/models": { "get": { "tags": [ "playground" ], "summary": "Load Playground model catalog", "description": "Returns Venice models and traits for the Playground, plus supported video fallbacks such as Seedance when Venice quote accepts them before model discovery lists them. Supported type filters are text, image, tts, video, and music.", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "text", "image", "tts", "video", "music" ], "default": "text" } } ], "responses": { "200": { "description": "Models and traits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundModelsResponse" } } } }, "400": { "description": "Unsupported model type" }, "429": { "description": "Rate limited" }, "502": { "description": "Failed to load Venice models" } } }, "post": { "tags": [ "playground" ], "summary": "Load Playground model catalog from JSON body", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image", "tts", "video", "music" ] } } } } } }, "responses": { "200": { "description": "Models and traits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundModelsResponse" } } } }, "400": { "description": "Unsupported model type" }, "429": { "description": "Rate limited" }, "502": { "description": "Failed to load Venice models" } } } }, "/api/playground/chat": { "post": { "tags": [ "playground" ], "summary": "Proxy a Playground chat completion to Venice", "description": "Uses a buyer-supplied CheapTokens/Venice API key server-side, with optional streaming, web search, and Venice parameter controls.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundChatRequest" } } } }, "responses": { "200": { "description": "Venice chat response or text/event-stream when stream=true" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited" }, "500": { "description": "Request failed" }, "502": { "description": "Venice chat request failed" } } } }, "/api/playground/image": { "post": { "tags": [ "playground" ], "summary": "Proxy a Playground image generation request to Venice", "description": "Uses a buyer-supplied CheapTokens/Venice API key server-side. Safe mode is permanently on for now: the backend always forwards safe_mode: true even if a crafted client request tries to disable it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundImageRequest" } } } }, "responses": { "200": { "description": "Venice image response" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited" }, "500": { "description": "Request failed" }, "502": { "description": "Venice image request failed" } } } }, "/api/playground/speech": { "post": { "tags": [ "playground" ], "summary": "Proxy a Playground text-to-speech request to Venice", "description": "Uses a buyer-supplied CheapTokens/Venice API key server-side and returns an audio data URL for browser playback.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundSpeechRequest" } } } }, "responses": { "200": { "description": "Generated speech audio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundSpeechResponse" } } } }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited" }, "500": { "description": "Request failed" }, "502": { "description": "Venice speech request failed" } } } }, "/api/playground/video": { "post": { "tags": [ "playground" ], "summary": "Proxy Playground video generation jobs to Venice", "description": "Uses a buyer-supplied CheapTokens/Venice API key server-side. The action field controls quote, queue, and retrieve calls for Venice video jobs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundVideoRequest" } } } }, "responses": { "200": { "description": "Video quote, queued job status, retrieve status JSON, or generated video bytes" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited" }, "500": { "description": "Request failed" }, "502": { "description": "Venice video request failed" } } } }, "/api/playground/music": { "post": { "tags": [ "playground" ], "summary": "Proxy Playground music generation jobs to Venice", "description": "Uses a buyer-supplied CheapTokens/Venice API key server-side. The action field controls quote, queue, and retrieve calls for Venice audio/music jobs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundMusicRequest" } } } }, "responses": { "200": { "description": "Music quote, queued job status, retrieve status JSON, or generated audio bytes" }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited" }, "500": { "description": "Request failed" }, "502": { "description": "Venice music request failed" } } } } }, "components": { "schemas": { "PricingResponse": { "type": "object", "required": [ "date", "pricingModel", "demandAdjustmentEnabled", "pricePerMillionTokens", "discountPercent", "discountMultiplier", "standardPrice", "baseDiscount", "finalDiscount", "adjustment", "sellThroughRate", "hourUTC", "creditsPerDollar", "timestamp", "supply" ], "properties": { "date": { "type": "string" }, "pricingModel": { "type": "string", "enum": [ "time_decay", "legacy_reservation_flat" ] }, "demandAdjustmentEnabled": { "type": "boolean" }, "pricePerMillionTokens": { "type": "number" }, "discountPercent": { "type": "number" }, "discountMultiplier": { "type": "number" }, "tier": { "type": [ "string", "null" ] }, "standardPrice": { "type": "number" }, "baseDiscount": { "type": "number" }, "finalDiscount": { "type": "number" }, "adjustment": { "type": "number", "description": "Backward-compatible field. Additional price adjustment is disabled and this is always 0." }, "sellThroughRate": { "type": "number", "description": "Capacity telemetry only. This does not affect Same-Day pricing." }, "hourUTC": { "type": "number" }, "creditsPerDollar": { "type": "number" }, "timestamp": { "type": "number" }, "supply": { "type": "object", "properties": { "effectiveSupply": { "type": "number" }, "sold": { "type": "number" }, "remaining": { "type": "number" } } } } }, "SupplyResponse": { "type": "object", "required": [ "date", "dailyCapacityUsd", "grossSoldUsd", "sameDaySoldUsd", "reservedUsd", "remainingUsd", "buyableRemainingUsd", "soldOut", "resetsAt", "resetsInMs", "minPurchaseUsd", "stepUsd", "availablePresets", "timestamp" ], "properties": { "date": { "type": "string" }, "dailyCapacityUsd": { "type": "number" }, "grossSoldUsd": { "type": "number" }, "sameDaySoldUsd": { "type": "number" }, "reservedUsd": { "type": "number" }, "remainingUsd": { "type": "number" }, "buyableRemainingUsd": { "type": "number" }, "soldOut": { "type": "boolean" }, "resetsAt": { "type": "string", "format": "date-time" }, "resetsInMs": { "type": "number" }, "minPurchaseUsd": { "type": "number" }, "stepUsd": { "type": "number" }, "availablePresets": { "type": "array", "items": { "type": "number" } }, "timestamp": { "type": "number" }, "capacityWarning": { "type": "object", "properties": { "message": { "type": "string" }, "shortfallMDiem": { "type": "number" }, "peakDate": { "type": "string" } } } } }, "BuyRequest": { "type": "object", "required": [ "usdPaid" ], "additionalProperties": false, "properties": { "usdPaid": { "type": "number", "minimum": 0.5, "description": "Discounted USD amount to pay before card fees. Minimum is based on receiving at least $0.50 in credits after current time-based pricing." }, "purchaseMode": { "type": "string", "enum": [ "spot", "prepaid" ], "default": "spot", "description": "spot creates Same-Day Credits; prepaid creates or tops up a Prepaid API Key." }, "dailyReservedUsd": { "type": "number", "minimum": 0.1, "description": "Daily credit reserve in Venice API credits per UTC day. Required when creating a Prepaid API Key. Must fit the unreserved capacity available for the start date and be at least one-seventh of the reserve balance." }, "reserveStart": { "type": "string", "enum": [ "tomorrow" ], "default": "tomorrow", "description": "New Prepaid API Keys start tomorrow UTC. Same-Day Credits are the product for work today." }, "topUpKeyLast6": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Last 6 characters of an active wallet-owned Prepaid API Key to top up via x402." }, "paymentSessionId": { "type": "string", "description": "Opaque session id returned in a prior 402 response; echo it back on retry." } } }, "BuySuccessResponse": { "type": "object", "description": "Representative x402 success schema for Same-Day, Prepaid, and Prepaid top-up purchases.", "properties": { "success": { "type": "boolean" }, "veniceApiKey": { "type": "string" }, "veniceKeyLast6": { "type": "string" }, "purchase": { "$ref": "#/components/schemas/PurchaseSummary" }, "purchaseId": { "type": "string", "deprecated": true, "description": "Legacy top-level id retained for older clients." }, "creditsIssuedUsd": { "type": "number", "deprecated": true, "description": "Legacy top-level value retained for older clients." }, "settlementTxHash": { "type": [ "string", "null" ] }, "paymentSessionId": { "type": [ "string", "null" ] }, "topUp": { "type": "boolean" }, "message": { "type": "string" } } }, "StatusResponse": { "type": "object", "required": [ "status", "dates", "creditsIssuedUsd", "diemAmount", "expiresAt", "veniceKeyLast6", "paymentMethod", "veniceUsage" ], "properties": { "status": { "type": "string", "enum": [ "active", "expired", "fulfilled", "reserved", "pending", "paid_pending_fulfillment", "failed" ] }, "dates": { "type": "array", "items": { "type": "string" } }, "creditsIssuedUsd": { "type": "number" }, "diemAmount": { "type": "number", "description": "Legacy internal credit unit expressed as USD-equivalent DIEM." }, "expiresAt": { "type": "string", "format": "date-time" }, "veniceKeyLast6": { "type": "string" }, "paymentMethod": { "type": [ "string", "null" ], "enum": [ "x402", "stripe_card", "rhino", null ] }, "reservedForDate": { "type": [ "string", "null" ], "deprecated": true, "description": "Legacy scheduled-capacity field; normally null for current Same-Day and Prepaid flows." }, "isStableKey": { "type": "boolean", "deprecated": true, "description": "Legacy internal name. true means this is a Prepaid API Key." }, "keyBalanceUsd": { "type": [ "number", "null" ], "description": "Current prepaid balance for Prepaid API Keys." }, "dailyReservedCapacityUsd": { "type": [ "number", "null" ], "description": "Selected daily credit reserve for Prepaid API Keys." }, "prepaid": { "anyOf": [ { "$ref": "#/components/schemas/PrepaidSummary" }, { "type": "null" } ] }, "veniceUsage": { "type": [ "object", "null" ], "additionalProperties": true } } }, "VenicePricingModel": { "type": "object", "required": [ "name", "id", "input", "output", "context", "privacy" ], "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "input": { "type": "number" }, "output": { "type": "number" }, "cacheRead": { "type": [ "number", "null" ] }, "context": { "type": "string" }, "privacy": { "type": "string", "enum": [ "Private", "Anonymized", "E2EE", "Unknown" ] } } }, "VenicePricingResponse": { "type": "object", "required": [ "count", "models", "source", "updatedAt" ], "properties": { "count": { "type": "number" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/VenicePricingModel" } }, "source": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WalletAuthRequest": { "type": "object", "required": [ "walletAddress", "signature", "nonce", "issuedAt" ], "properties": { "walletAddress": { "type": "string" }, "signature": { "type": "string" }, "nonce": { "type": "string" }, "issuedAt": { "type": "string", "format": "date-time" } } }, "WalletPurchasesResponse": { "type": "object", "required": [ "purchases" ], "properties": { "purchases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "dates": { "type": "array", "items": { "type": "string" } }, "paidUsd": { "type": "number" }, "creditsIssuedUsd": { "type": "number" }, "creditsConsumedUsd": { "type": [ "number", "null" ] }, "creditsRemainingUsd": { "type": [ "number", "null" ] }, "diemAmount": { "type": "number" }, "expiresAt": { "type": "string", "format": "date-time" }, "veniceKeyLast6": { "type": [ "string", "null" ] }, "hasKey": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentMethod": { "type": [ "string", "null" ] }, "reservedForDate": { "type": [ "string", "null" ], "description": "Legacy scheduled-capacity field; normally null for current Same-Day and Prepaid flows.", "deprecated": true }, "canReissue": { "type": "boolean" }, "purchaseMode": { "type": "string", "enum": [ "spot", "prepaid" ] }, "isStableKey": { "type": "boolean", "deprecated": true, "description": "Legacy internal name. true means Prepaid API Key." }, "keyBalanceUsd": { "type": [ "number", "null" ] }, "dailyReservedCapacityUsd": { "type": [ "number", "null" ] }, "prepaid": { "anyOf": [ { "$ref": "#/components/schemas/PrepaidSummary" }, { "type": "null" } ] }, "canTopUp": { "type": "boolean" } } } } } }, "PurchaseSummary": { "type": "object", "properties": { "id": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } }, "dates": { "type": "array", "items": { "type": "string" } }, "usdPaid": { "type": "number" }, "creditsIssuedUsd": { "type": "number" }, "discountMultiplier": { "type": "number" }, "expiresAt": { "type": "string", "format": "date-time" }, "purchaseMode": { "type": "string", "enum": [ "spot", "prepaid" ] }, "dailyReservedUsd": { "type": [ "number", "null" ] }, "keyBalanceUsd": { "type": [ "number", "null" ] }, "reserveStartsOn": { "type": [ "string", "null" ] }, "reserveDebitedToday": { "type": [ "boolean", "null" ] }, "settlementTxHash": { "type": [ "string", "null" ] } } }, "PrepaidSummary": { "type": "object", "additionalProperties": true, "properties": { "reserveStartsOn": { "type": [ "string", "null" ] }, "nextResetAt": { "type": [ "string", "null" ], "format": "date-time" }, "totalPrepaidUsd": { "type": "number" }, "currentBalanceUsd": { "type": "number" }, "dailyReservedUsd": { "type": [ "number", "null" ] }, "balanceRunwayDays": { "type": [ "number", "null" ] }, "fundedCreditDays": { "type": [ "number", "null" ] }, "creditsThroughDate": { "type": [ "string", "null" ] }, "activity": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CheckoutOptionsResponse": { "type": "object", "required": [ "recommended", "agentDefault", "today", "resetsAt", "stableKey", "routes" ], "properties": { "recommended": { "type": "string" }, "agentDefault": { "type": "string" }, "amountUsd": { "type": [ "number", "null" ] }, "dateMode": { "type": "string", "enum": [ "today", "future" ] }, "today": { "type": "string" }, "resetsAt": { "type": "string", "format": "date-time" }, "stableKey": { "type": "object", "description": "Legacy field name for Prepaid API Key availability.", "additionalProperties": true }, "routes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agentHint": { "type": "string" } } }, "StripeCheckoutRequest": { "type": "object", "required": [ "creditsRequestedUsd" ], "properties": { "creditsRequestedUsd": { "type": "number", "minimum": 0.5 }, "purchaseMode": { "type": "string", "enum": [ "spot", "prepaid" ], "default": "spot" }, "dailyReservedUsd": { "type": "number", "description": "Required for Prepaid API Key checkout. Must fit the unreserved capacity available for the start date and be at least one-seventh of the reserve balance." }, "reserveStart": { "type": "string", "enum": [ "tomorrow" ], "default": "tomorrow", "description": "New Prepaid API Keys start tomorrow UTC. Same-Day Credits are the product for work today." }, "customerEmail": { "type": "string", "format": "email" } } }, "StripeCheckoutResponse": { "type": "object", "required": [ "url", "sessionId", "orderId", "quote" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "sessionId": { "type": "string" }, "orderId": { "type": "string" }, "quote": { "type": "object", "additionalProperties": true } } }, "StripeOrderResponse": { "type": "object", "required": [ "ready", "order" ], "properties": { "ready": { "type": "boolean" }, "order": { "type": "object", "additionalProperties": true }, "purchase": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseSummary" }, { "type": "null" } ] }, "veniceApiKey": { "type": "string" }, "veniceKeyLast6": { "type": "string" }, "message": { "type": "string" } } }, "StripeRecoverRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "StripeRecoverResponse": { "type": "object", "required": [ "ok", "message" ], "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }, "StripeRecoverClaimRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 24, "maxLength": 256 } } }, "StripeRecoverClaimResponse": { "type": "object", "required": [ "ready", "expiresAt", "keys" ], "properties": { "ready": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "object", "additionalProperties": true }, "purchase": { "type": "object", "additionalProperties": true }, "veniceApiKey": { "type": "string" }, "veniceKeyLast6": { "type": "string" } } } } } }, "PlaygroundModelsResponse": { "type": "object", "required": [ "type", "models", "traits", "fetchedAt" ], "properties": { "type": { "type": "string", "enum": [ "text", "image", "tts", "video", "music" ] }, "models": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "traits": { "type": [ "object", "null" ], "additionalProperties": true }, "fetchedAt": { "type": "string", "format": "date-time" } } }, "PlaygroundChatRequest": { "type": "object", "required": [ "apiKey", "model", "userMessage" ], "properties": { "apiKey": { "type": "string" }, "model": { "type": "string" }, "userMessage": { "type": "string", "maxLength": 12000 }, "systemPrompt": { "type": "string", "maxLength": 8000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 0.7 }, "maxCompletionTokens": { "type": "integer", "minimum": 1, "maximum": 8192, "default": 1024 }, "stream": { "type": "boolean", "default": true }, "includeVeniceSystemPrompt": { "type": "boolean", "default": true }, "disableThinking": { "type": "boolean", "default": false }, "webSearch": { "type": "string", "enum": [ "off", "auto", "on" ], "default": "off" } } }, "PlaygroundImageRequest": { "type": "object", "required": [ "apiKey", "model", "prompt" ], "properties": { "apiKey": { "type": "string" }, "model": { "type": "string" }, "prompt": { "type": "string", "maxLength": 7500 }, "negativePrompt": { "type": "string", "maxLength": 2000 }, "format": { "type": "string", "enum": [ "webp", "png", "jpeg" ], "default": "webp" }, "sizingMode": { "type": "string", "enum": [ "dimensions", "aspect" ], "default": "dimensions" }, "width": { "type": "integer", "minimum": 256, "maximum": 1280, "default": 1024 }, "height": { "type": "integer", "minimum": 256, "maximum": 1280, "default": 1024 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "variants": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 }, "steps": { "type": "integer", "minimum": 1, "maximum": 50, "default": 8 }, "cfgScale": { "type": "number", "minimum": 0.1, "maximum": 20, "default": 7.5 }, "seed": { "type": "integer", "minimum": -999999999, "maximum": 999999999, "default": 0 }, "safeMode": { "type": "boolean", "default": true, "readOnly": true, "description": "Ignored if false. CheapTokens always forwards safe_mode: true to Venice." } } }, "PlaygroundSpeechRequest": { "type": "object", "required": [ "apiKey", "model", "voice", "input" ], "properties": { "apiKey": { "type": "string" }, "model": { "type": "string" }, "voice": { "type": "string" }, "input": { "type": "string", "maxLength": 4096 }, "responseFormat": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ], "default": "mp3" }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "default": 1 }, "prompt": { "type": "string", "maxLength": 500 }, "language": { "type": "string", "maxLength": 40 } } }, "PlaygroundSpeechResponse": { "type": "object", "required": [ "audioDataUrl", "contentType", "byteLength", "generatedAt" ], "properties": { "audioDataUrl": { "type": "string" }, "contentType": { "type": "string" }, "byteLength": { "type": "number" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "PlaygroundVideoRequest": { "type": "object", "required": [ "apiKey", "model", "action" ], "properties": { "apiKey": { "type": "string" }, "model": { "type": "string" }, "action": { "type": "string", "enum": [ "quote", "queue", "retrieve" ] }, "prompt": { "type": "string", "maxLength": 15000, "description": "Required when action is queue." }, "negativePrompt": { "type": "string", "maxLength": 2500 }, "queueId": { "type": "string", "maxLength": 120, "description": "Required when action is retrieve." }, "duration": { "type": "string", "pattern": "^(Auto|[1-9]\\d?s)$", "default": "5s", "description": "Provider-supported video duration enum, such as 5s, 10s, 15s, 30s, or Auto. Check /api/playground/models for the selected model's durations." }, "aspectRatio": { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "auto", "9:16", "9:21", "16:9", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "pattern": "^(true_)?\\d{3,4}[pP]$|^\\d[Kk]$|^\\d+x$", "default": "720p", "description": "Provider-specific video quality/resolution forwarded as resolution, such as 720p, 1080p, 768P, 2K, 4k, true_1080p, 2x, or 4x. Check /api/playground/models for the selected model's resolutions." }, "upscaleFactor": { "type": "number", "enum": [ 1, 2, 4 ], "description": "Forwarded to Venice as upscale_factor for video upscale models." }, "audio": { "type": "boolean", "default": false }, "imageUrl": { "type": "string", "description": "Image URL or data URL forwarded to Venice as image_url for image-to-video models." }, "endImageUrl": { "type": "string", "description": "Optional end image URL or data URL forwarded to Venice as end_image_url." }, "videoUrl": { "type": "string", "description": "Video URL or data URL forwarded to Venice as video_url for video-to-video, motion-control, and upscale models." }, "audioUrl": { "type": "string", "description": "Optional audio URL or data URL forwarded to Venice as audio_url when a video model supports audio input." }, "referenceImageUrls": { "type": "array", "maxItems": 9, "items": { "type": "string" }, "description": "Reference image URLs or data URLs forwarded to Venice as reference_image_urls." } } }, "PlaygroundMusicRequest": { "type": "object", "required": [ "apiKey", "model", "action" ], "properties": { "apiKey": { "type": "string" }, "model": { "type": "string" }, "action": { "type": "string", "enum": [ "quote", "queue", "retrieve" ] }, "prompt": { "type": "string", "maxLength": 5000, "description": "Required when action is queue." }, "lyricsPrompt": { "type": "string", "maxLength": 4000 }, "queueId": { "type": "string", "maxLength": 120, "description": "Required when action is retrieve." }, "durationSeconds": { "type": [ "integer", "null" ], "minimum": 3, "maximum": 600, "default": 60 }, "forceInstrumental": { "type": "boolean", "default": true }, "voice": { "type": "string", "maxLength": 120 }, "languageCode": { "type": "string", "maxLength": 16 }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 } } } } } }