# From a thought to a useful result. Noemad brings models, wallet identity, usage pricing, and Monad settlement into one workspace. Monad Testnet release. Live wallet sessions, API keys and one qualified chat route are connected. Sample mode remains available. Public wallet-payment acceptance and broader model qualification are tracked separately. ## One interface, multiple providers Noemad connects a wallet-owned account to model capabilities through a modular Go gateway. Provider credentials and routing stay on the server. Users approve a spending maximum for each paid operation; the service settles the measured actual charge on Monad. Quickstart Run your first testnet request. Model catalog Discover capability reference data. Workspace Keys, usage, logs and billing. Payments Maximum approval, actual settlement. ## Product surfaces SurfacePurposePlaygroundChat, media, realtime, retrieval and evaluation interfacesModel catalog and calculatorCapabilities, unit-specific rates and request estimatesWorkspaceWallet-owned keys, usage, logs and receiptsOperator consoleSeparate operational interface previewStatus and changelogMonitoring states and development notes ## Current implementation The dashboard connects wallet sign-in, product keys, qualified chat, usage and receipts to the Go gateway. Other modalities and the operator console remain previews. Read the implementation status and the project repository. --- # Your first request Choose a capability, review a maximum, and keep the result with its receipt. ## 1. Open your workspace Start in the dashboard, playground, or capability playground. Live mode uses the server catalog. The Sample data switch opens local examples. ## 2. Connect your wallet Choose Connect wallet and select an installed EVM wallet. Connection shares your selected address. Choose Sign in with wallet to approve a separate SIWE challenge. Select Monad Testnet for payments; the wallet needs testnet USDC and MON for its initial token approval. ## 3. Choose a model and limits Inspect the model capability, input type, output limit and applicable unit. The live gateway snapshots the billing policy and maximum for this request. The browser calculator is a reference, not the authority for a payment. ## 4. Review the maximum Review the model, maximum, testnet token, merchant, expiry and rounding policy. If needed, approve a bounded USDC allowance, then authorize this inference separately. Network fees are separate. Signing in does not grant permission to pay. ## 5. Read the result and receipt After authorization, the gateway can stream the output. Reliable usage determines the actual charge within your cap. Settlement status is retrieved separately; output success and confirmed payment are different states. ## Try it now Open the live playground. The current chat route has a 0.01 testnet USDC maximum and a 512-token output limit. Its actual charge follows the supplier bill. Sample mode signs and transfers nothing. ## Next steps Wallet & sign-in Connect an address and understand each permission. API reference Explore request formats and capability guides. Monad payments Review your maximum, usage and settlement. --- # Your wallet is your identity Wallet connection, sign-in, and spending authorization are separate permissions. ## Connect an installed wallet The UI uses EIP-6963 discovery with an EIP-1193 injected-provider fallback. Address access is requested only after you choose a wallet. Private keys and recovery phrases are never requested. Mobile wallets must expose an injected provider in their in-app browser. WalletConnect QR pairing is not connected in this preview. ## Verify ownership The server validates the SIWE challenge, domain, URI, chain, nonce, time and origin. Nonces are single-use. Sessions use Secure, HttpOnly, SameSite cookies and CSRF protection. Reload recovers the same session-bound CSRF token; sign-out revokes the session. Contract-wallet support must be qualified before it is advertised. ``` POST /_monad/v1/auth/challenge POST /_monad/v1/auth/verify ``` ## Wallet-owned API keys Product keys belong to the wallet account and scope access to its own requests, files, jobs and usage. They are not provider credentials and do not automatically authorize wallet spending. ## Authorize a bounded request The x402 v2 upto flow uses the pinned SDK’s Permit2/proxy mechanism. Allowance and request authorization are reviewed separately when needed. The signed maximum limits collection; it does not reserve wallet funds. ## Account changes Disconnect or account changes clear the live wallet data and revoke the previous session. Each inference needs an explicit payment authorization. Manage wallet site permissions and remaining token allowance inside your wallet. --- # Models, streams, and capabilities A qualified model route keeps its request contract while adding explicit payment terms. ## Choose a qualified route The product plan preserves familiar Chat Completions, Responses and Messages payloads and streams. Media, files, jobs, realtime, embeddings, rerank and structured evaluation retain their own contracts when enabled. ``` { "model": "", "messages": [ { "role": "user", "content": "Turn this product brief into a clear summary." } ], "max_completion_tokens": 512, "stream": true } ``` ## Bind the quote The quote binds the owner, method, path, canonical body, provider, model, rate snapshot, limits, maximum, asset, chain, recipient and expiry. Changing the model or cost-relevant inputs requires a new quote. ## Stream without losing payment state Output can begin after authorization verification. The gateway forwards the qualified protocol’s JSON/SSE and records usage and outcome. Final settlement is retrieved separately; the initial stream headers cannot be updated after delivery begins. ## Validate usage and outcome A successful HTTP status alone does not prove a usable response or billable usage. Missing final usage, a partial stream, a timeout after dispatch, or a crashed worker enters the applicable recovery or reconciliation state. ## Provider modularity Each adapter implements capability discovery, pricing, invocation, usage mapping and health. A different provider/model/rate cannot silently replace approved terms. See provider architecture. --- # Approve a maximum. Pay for usage. The x402 v2 upto flow separates authorization from actual settlement. ## Review a model-specific quote There is no user app balance to top up. Pricing comes from the selected model and parameters. The gateway freezes the rate snapshot, unit, modifiers, conversion policy, limits and expiry for the operation. FieldMeaningMaximumAn enforceable upper bound you approve before dispatchActual amountCalculated from reliable request usage and the frozen rateNetworkMonad; chain, token, proxy and facilitator must come from verified configurationMechanismx402 v2 upto, using the pinned Permit2/proxy implementationNetwork feeSeparate from inference; sponsorship must be verifiedCurrent chat routeLive chat maximum: 0.01 testnet USDC. The actual amount remains pending until the supplier bill is resolved. ## The request lifecycle Validate the capability, capacity and model rate. Create an immutable quote and return a payment challenge. Review the quote and any required allowance. Sign the bounded request authorization in the wallet. Verify and claim one operation before dispatch. Forward output and record reliable usage. Persist the actual amount and unique settlement job. Verify the matching onchain receipt before marking collection settled. ## The unused amount stays in your wallet The maximum is not transferred first. Settling less than the maximum leaves the difference in your wallet; it is not a refund. Authorization also does not lock your balance, so later collection can fail. ## Metering and rounding Chat separates ordinary input, cache-read and output under the model’s usage definition. Media uses its actual units. Money uses integer/fixed-point values. Current policy converts 100,000,000 nominal Amanai credits to 1 USDC and rounds the final request charge up once to 0.000001 USDC. The platform fee is zero. The supplier bill already incorporates model and cache pricing; the gateway does not charge cache twice. ## Uncertainty and zero charge Missing usage is not permission to charge the maximum. Reconcile uncertain outcomes. A free or rounded-zero operation closes as zero-charge without inventing a transaction. Poll the existing operation; the gateway reconciles uncertain settlement and does not blindly send a second payment. ## Implementation status The backend has a recorded testnet wallet payment below its cap. The public dashboard uses the SDK checked against the Go verifier; acceptance of a new signed request through this deployed UI is tracked separately. Other models, mainnet and media payments are not enabled. Protocol references: Monad x402 guide and EVM upto specification. --- # Application and inference API Familiar inference contracts with explicit wallet and payment extensions. Runtime v1.2. The public API shares this origin. Only qualified routes from /calculate/models are enabled. The current live model is amanai/gpt-6-luna for Chat Completions. ## Endpoint directory Chat Messages, Responses and tools. Media Image, video and speech requests. Realtime Live WebRTC voice sessions. Embeddings Text vectors and bounded batches. Rerank Query and document relevance. Evaluation Typed answers from state and questions. ## Public surfaces SurfaceContract/v1/chat/completions, /v1/responses, /v1/messagesProduct key or supported playground session; qualified reference JSON/SSE/v1/models and /v1/usageQualified catalog and owner-scoped usageFiles, jobs and modality routesOriginal resource contract with product ownership checks/_monad/v1/auth/challenge and /_monad/v1/auth/verifyWallet challenge and verificationGET /_monad/v1/operations/{id}Owner-only inference and collection status ## Payment headers ``` PAYMENT-REQUIRED PAYMENT-SIGNATURE PAYMENT-RESPONSE Idempotency-Key X-Monad-Operation-Id ``` The Idempotency-Key binds a credential, route and request body to one operation. A payment-aware client preserves the exact key and body when submitting authorization. Generic clients do not automatically understand this extension. Final payment status may arrive after streaming, through the owner-only receipt endpoint. ## Request example ``` POST /v1/chat/completions Authorization: Bearer Content-Type: application/json Idempotency-Key: PAYMENT-SIGNATURE: { "model": "", "messages": [ { "role": "user", "content": "Summarize this brief." } ], "max_completion_tokens": 512, "stream": true } ``` ## Ownership and retries One chain/token/payer/nonce/spender tuple binds to one operation. Scope idempotency to owner, route and canonical body. Repeated proof reads existing state rather than dispatching a second request. Shared provider accounts never expose another wallet’s resources. ## Compatibility directory API compatibility Shared headers, errors and request lifecycle. SDK & CLI Configure clients and payment-aware tools. Reseller API Operator procurement and provider orders. --- # Keep inference and payment distinct A result, a usage record, and a collection receipt describe different parts of one operation. ## Separate state machines ``` Operation: quoted → authorized → dispatched → streaming / completed / failed / unknown Collection: none → authorized → ready → settling → settled / zero_charge / unknown / failed ``` ## What a receipt must contain Record the owner, quote, model, rate snapshot, limits, usage, maximum, actual amount, asset, chain, recipient, operation outcome and collection state. Include a transaction hash only after an actual transaction has been observed and verified. ## Recover without dispatching again Retrieve the existing operation or result. A payment timeout does not mean inference should be rerun. Settlement retries reuse the immutable actual amount and authorization binding. Reconciliation verifies the matching receipt, spender, nonce, payer and recipient. ## Ambiguous or partial results Partial billable delivery follows the frozen policy when usage is reliable. Missing usage or ambiguous dispatch requires reconciliation. Do not silently fall back to a different provider, replay a side effect, or charge a guessed maximum. ## Local demo receipts Preview receipts are saved only in this browser. They contain sample usage and pricing, no real signature or transaction hash. Download them to keep a copy; clearing browser storage removes them. --- # One product. Modular providers. A Go gateway connects wallet identity, capability adapters, metering, and Monad settlement. ## Request topology ``` Browser / SDK + user wallet │ session or product key + bounded authorization ▼ Go gateway ─── provider adapter ─── model API │ │ output + usage ├── PostgreSQL: quotes, operations, usage, journals └── Settlement workers → x402 facilitator → Monad │ └── verified receipt / reconciliation ``` ## Clear module boundaries Identity, catalog, quotes, operations, usage, accounting, payment and reconciliation have separate responsibilities. Adapters implement provider formats and qualified capabilities behind ports. A new provider does not replace the wallet/payment core. ## Durable accounting Persist usage, outcome, immutable charge and unique settlement job atomically. Workers use leases and fencing. Provider and RPC network calls happen outside database transactions. Keep anti-replay proof and accounting journals beyond content retention. ## No user deposits The operator funds provider accounts. The user holds their own Monad tokens and authorizes a request maximum. Authorization does not reserve funds, so the operator must bound outstanding collection liability. ## Implementation reference The architecture, payment design, and protocol remain implementation specifications. --- # Know where your data goes Wallet identity, offchain requests, onchain settlement, and local preview storage. ## Local preview data Demo prompts, receipts and workspace fixtures are saved in this browser. Theme and motion preferences are also local. Local samples do not call a model or submit payments. A wallet connection can contact your installed wallet after an explicit choice. ## Live request processing The service and selected model provider process prompts and outputs offchain. The gateway does not need to forward wallet session cookies, payment signatures or private keys to the model provider. ## Public blockchain information Wallet addresses and settlement transactions are publicly linkable. Pseudonymous wallet access is not anonymity. Prompts should not be placed in onchain transaction metadata. ## Ownership and retention The gateway must scope keys, usage, files, jobs and artifacts to the product owner even when it uses a shared provider account. Retention periods and provider policies require confirmation before launch; this preview does not promise zero retention or no training. ## Trust pages See the trust center, privacy outline, and browser storage notice. --- # What is connected Live testnet capabilities and the remaining acceptance gates. ## Available to explore Responsive landing, original classical artwork, animations, dark/light mode. Wallet discovery/address connection and wallet-only entry screens. Local Playground walkthrough, sample receipts, search/copy/download. Public catalog, status, changelog, policy, and detailed capability docs. Separate personal dashboard built with shadcn/ui: overview, playground, calculator, logs, usage, payments, rewards, billing, and API keys. Operator and multimodal lab previews remain separate. ## Connected on testnet Wallet SIWE sessions, reload recovery, and scoped API keys. Qualified Chat Completions through Amanai, with JSON and SSE support. Explicit bounded Permit2 approval and per-request authorization. Owner-scoped operation history, supplier billing and settlement status. Go API, PostgreSQL and encrypted result storage behind a dedicated Cloudflare tunnel. ## Remaining acceptance The backend has a confirmed testnet payment; the deployed dashboard still needs its own signed wallet canary. Media, all-model qualification, refunds, mainnet, monitoring and disaster recovery are separate gates. Sample mode and the operator console remain illustrative. ## Service health is separate The service status page represents telemetry readiness. It does not report invented uptime or treat absent monitoring as an outage. ## Latest product scope The current specification replaces the earlier single-profile fixed-price concept with model-specific usage pricing and modular providers. Only Sample mode is illustrative. Live mode uses the deployed gateway and requires explicit wallet consent for payments. --- # Provider architecture One product contract, several qualified inference adapters. Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified. ## Product core and provider adapters Noemad owns wallet identity, product API keys, model discovery, immutable quotes, payment authorization, usage attribution, receipts, and recovery. A provider adapter owns authentication to a model service, native request conversion, stream parsing, usage normalization, and safe error mapping. The product is designed for all qualified models and modalities. Adding a provider is more than changing a base URL: authentication, content blocks, reasoning controls, tool semantics, asynchronous jobs, usage fields, and error envelopes can differ. SurfaceProduct coreAdapterIdentityWallet owner, product session, scoped keyOperator service credentialCatalogOwner entitlement and enabled routesProvider model and capability discoveryPricingPinned snapshot, conversion policy, maximum, actual chargeModel units, modifiers, usage and provider costInferenceOne operation, request binding, delivery stateInvoke / stream with bounded deadlinesResourcesOwner-scoped file, job, session and artifact grantsNative IDs and provider lifecycleRecoveryJournal, outbox, collection status, reconciliationProven lookup and idempotency behavior ## A modular adapter contract ``` type Provider interface { Discover(ctx Context, scope Scope) (Catalog, error) Quote(ctx Context, request NormalizedRequest) (PriceSpec, error) Invoke(ctx Context, request NormalizedRequest, out Stream) (Outcome, error) Lookup(ctx Context, ref ProviderReference) (Outcome, error) Health(ctx Context) (Observation, error) } // Conceptual interface. Capabilities and optional lookup support are explicit. ``` ## Keep credentials behind the product boundary The operator’s provider key remains in server-side secret storage. A Noemad product key belongs to a wallet owner and must never be forwarded as a provider credential. A shared provider account does not make its balance, logs, files, jobs, or conversation data visible to every product user. Every resource request is authorized against the product owner before it reaches the adapter. Provider-native IDs are mapped to owner-scoped product IDs. File and artifact access must not rely on an unguessable URL alone. ## Bind the selected adapter to the quote The quote records the provider ID, model ID, route, canonical body hash, rate snapshot, modifiers, conversion policy, enforced usage limits, maximum amount, chain, asset, merchant, allowed facilitator/proxy, and expiry. Accepted operations retain that snapshot when future rates change. Keep the provider’s internal identity in trusted configuration. The public product is Noemad; no upstream provider is presented as its sole identity. ## Preserve protocol behavior Chat Completions, Responses, and Messages keep their documented JSON and streaming shapes. The adapter observes terminal events and usage while forwarding output; the service does not buffer an entire stream just to wait for settlement. The payment receipt is read separately after usage is final. Distinguish first-byte, idle, and total deadlines. An HTTP 200 or a few streamed tokens do not prove complete delivery. Unknown usage cannot be billed as the approved maximum. ## Fallback needs explicit permission and evidence A new model, provider, or rate outside the approved snapshot needs a new quote. After output or a side effect is committed, or dispatch is ambiguous, do not silently repeat the operation. A request ID is useful for correlation but is not proof of provider idempotency. Before supporting fallback, document which errors are definitively pre-dispatch, which operations can be looked up, and how costs and delivery guarantees are preserved. ## Qualification checklist Validate discovery with the actual scoped credential. Test each endpoint, input type, supported parameter, and output limit. Check JSON/SSE event order, tool history, terminal errors, and complete output. Verify usage attribution and pricing, including cache and modality units. Exercise disconnect, timeout, duplicate nonce, restart, and reconciliation cases. Publish data handling and the exact enabled capability set. Prove a second adapter can satisfy the contract without changing wallet/payment core. --- # Model catalog Discovery, capabilities, official pricing sources, and model specifications. Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified. ## Authenticated discovery is authoritative GET /v1/models returns the models available to the product key or supported owner session. A public model name does not prove provider entitlement, quota, health, or an enabled Noemad route. Only qualified models may be presented as runnable. ``` GET /v1/models GET /v1/models?type=embedding GET /v1/models?type=rerank GET /calculate/models ``` /calculate/models describes quoteable pricing specifications. A fresh quote validates request-specific options and creates an immutable cost snapshot. The browser must not maintain a competing pricing engine for real payments. ## Capability fields FieldMeaningid / label / vendorStable public identifier, display name, and model developermodality / input_modalitiesEndpoint family and accepted input kindscontext_length / max_outputPublished limits; the admitted request may be bounded more tightlythinkingSupported reasoning values, including auto or none only when declarednative_dimensions / dimensionsEmbedding shape and any supported selectable dimensionsmax_documentsRerank candidate boundpricing unit / minimum / modifierHow this exact configuration is measuredenabled / health / entitlementSeparate live deployment facts; absent data is unknown ## Complete archived model reference Model specification reference. Names and capability limits come from the imported catalog snapshot. Enabled models require fresh qualification. USD rates below are listed only when verified for the exact model against an official source; unverified prices are marked. The library preserves 63 catalog records plus 9 additional entries from the exported capability pages: two later chat entries, two video entries, three speech entries, realtime, and typed evaluation. Browse and filter the entire collection in the model library. FamilyReference recordsIntegration guideChat42Chat & textEmbeddings12EmbeddingsRerank5RerankImage6MediaVideo2Durable video jobsSpeech synthesis / transcription3AudioRealtime1RealtimeStructured evaluation1Typed decisions ## Chat capability records Model referenceInputContext / outputReasoningGLM 5.3glm-5.3text1,000,000 / 128,000auto, low, medium, high, xhigh, maxGLM 5.3 Flashglm-5.3-flashtext, image, video1,000,000 / 128,000auto, low, medium, high, xhigh, maxGLM 5.2glm-5.2text1,000,000 / 128,000auto, low, medium, high, xhigh, maxGLM 5.1glm-5.1text200,000 / 128,000auto, low, medium, highGLM 5.0 Turboglm-5.0-turbotext200,000 / 128,000auto, low, medium, highGLM 5V Turboglm-5v-turbotext, image, video200,000 / 128,000auto, low, medium, highMuse Spark 1.1muse-spark-1.1text1,048,576 / 1,000,000auto, none, low, medium, high, xhigh, maxMuse Spark 1.2muse-spark-1.2text1,048,576 / 1,000,000auto, none, low, medium, high, xhigh, maxQwen 3.8 Maxqwen3.8-maxtext, image, video1,000,000 / 64,000auto, none, low, medium, highQwen 3.7 Maxqwen3.7-maxtext1,000,000 / 64,000auto, none, low, medium, highQwen 3.7 Plusqwen3.7-plustext, image1,000,000 / 64,000auto, none, low, medium, highKimi K3kimi-k3text, image, video1,000,000 / 64,000auto, low, high, maxKimi K2.7kimi-k2.7text, image256,000 / 32,000auto, low, medium, highKimi K2.6kimi-k2.6text, image256,000 / 32,000auto, low, medium, highKimi K2.5kimi-k2.5text, image256,000 / 32,000auto, low, medium, highDeepSeek V4 Prodeepseek-v4-protext, image1,000,000 / 384,000auto, low, medium, highDeepSeek V4 Pro 0813deepseek-v4-pro-0813text1,000,000 / 384,000auto, none, low, medium, high, maxDeepSeek V4 Flashdeepseek-v4-flashtext1,000,000 / 384,000auto, low, medium, highDeepSeek V4.1 Flashdeepseek-v4.1-flashtext, image1,000,000 / 128,000auto, none, low, medium, high, maxDeepSeek V4 Flash 0731deepseek-v4-flash-0731text1,000,000 / 384,000auto, none, low, medium, high, maxMiniMax M3minimax-m3text, image, video1,000,000 / 48,000auto, low, medium, highMiniMax M2.7minimax-m2.7text, image200,000 / 48,000auto, low, medium, highHunyuan 3hy3text1,000,000 / 64,000auto, low, medium, highHunyuan 4hy4text1,000,000 / 64,000auto, low, medium, highGrok 4.5grok-4.5text, image, file500,000 / 64,000auto, minimal, low, medium, high, xhighGrok 4.6grok-4.6text, image, file500,000 / 64,000auto, low, medium, high, xhighGPT 5.5gpt-5.5text, image, file1,050,000 / 128,000auto, none, low, medium, high, xhighGPT 6 Astragpt-6-astratext, image, video, file1,050,000 / 128,000auto, low, medium, high, xhigh, maxGPT 5.6 Solgpt-5.6-soltext, image, file1,050,000 / 128,000auto, none, low, medium, high, xhigh, maxGPT 5.6 Terragpt-5.6-terratext, image, file1,050,000 / 128,000auto, none, low, medium, high, xhigh, maxGPT 5.6 Lunagpt-5.6-lunatext, image, file1,050,000 / 128,000auto, none, low, medium, high, xhigh, maxClaude Fable 5.1claude-fable-5.1text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Fable 5claude-fable-5text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Opus 5claude-opus-5text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Opus 4.8claude-opus-4.8text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Opus 4.7claude-opus-4.7text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Opus 4.6claude-opus-4.6text, image, file1,000,000 / 128,000auto, none, low, medium, high, xhigh, maxClaude Sonnet 5claude-sonnet-5text, image, file1,000,000 / 128,000auto, low, medium, high, xhigh, maxClaude Sonnet 4.6claude-sonnet-4.6text, image, file1,000,000 / 128,000auto, none, low, medium, high, xhigh, maxClaude Haiku 4.5claude-haiku-4.5text, image, file200,000 / 64,000auto, low, medium, high, xhigh, maxGLM 5.3 FlashXglm-5.3-flashxtext, image, video1,000,000 / 128,000Not specifiedGrok 4.7grok-4.7text, image, file500,000 / 64,000Not specified ## Specialized records Model referenceCapabilityNative dimension / boundGpt 5.5 Imagegpt-5.5-imageImagesAdapter-specificGpt 5.6 Luna Imagegpt-5.6-luna-imageImagesAdapter-specificGpt 5.6 Sol Imagegpt-5.6-sol-imageImagesAdapter-specificGpt 5.6 Terra Imagegpt-5.6-terra-imageImagesAdapter-specificGrok Imagine Imagegrok-imagine-imageImagesAdapter-specificGrok Imagine Image 2.0grok-imagine-image-2.0ImagesAdapter-specificBGE Small ENbge-small-enEmbeddings384 dimensionsBGE Base ENbge-base-enEmbeddings768 dimensionsBGE Large ENbge-large-enEmbeddings1024 dimensionsBGE-M3bge-m3Embeddings1024 dimensionsEmbeddingGemma 300Membeddinggemma-300mEmbeddings768 dimensionsQwen3 Embedding 0.6Bqwen3-embedding-0.6bEmbeddings1024 dimensionsBGE Reranker Basebge-reranker-baseRerank100 documentsvoyage-4-litevoyage-4-liteEmbeddings1024 dimensionsvoyage-4voyage-4Embeddings1024 dimensionsvoyage-4-largevoyage-4-largeEmbeddings1024 dimensionsvoyage-code-4voyage-code-4Embeddings1024 dimensionsvoyage-finance-2voyage-finance-2Embeddings1024 dimensionsvoyage-law-2voyage-law-2Embeddings1024 dimensionsVoyage rerank-3voyage-rerank-3Rerank100 documentsVoyage rerank-3-litevoyage-rerank-3-liteRerank100 documentsVoyage rerank-2.5voyage-rerank-2.5Rerank100 documentsVoyage rerank-2.5-litevoyage-rerank-2.5-liteRerank100 documentsGrok Imagine Videogrok-imagine-videoVideoAdapter-specificGrok Imagine Video 1.5grok-imagine-video-1.5VideoAdapter-specificGrok Voice TTSgrok-voice-ttsSpeech synthesisAdapter-specificGrok Voice Transcribe 1.0grok-voice-transcribe-1.0TranscriptionAdapter-specificGrok Voice Transcribe 2.0grok-voice-transcribe-2.0TranscriptionAdapter-specificGPT Livegpt-liveRealtimeAdapter-specificJev 1.13jev-1.13Structured evaluationAdapter-specific ## Changes are explicit A model alias, provider mapping, supported tool, rate, or maximum changes the request contract. Publish new configuration for future quotes and preserve accepted snapshots. If a provider cannot honor a pinned rate, the operator absorbs the difference or rejects before dispatch; it must not increase the user’s approved charge. --- # API compatibility Endpoint directory, authentication, headers, streaming, and errors. Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified. Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization. ## Two related API surfaces /v1 retains the inference request and response families. Wallet authentication and payment status are additional product endpoints. They do not replace Chat Completions, Responses, Messages, or specialized modality payloads with a single text-only wrapper. MethodPathPurposePOST/v1/chat/completionsChat Completions JSON / SSE; messages and toolsPOST/v1/responsesResponses JSON / event streamPOST/v1/messagesMessages content blocks / event streamPOST/v1/messages/count_tokensCompatible token count; qualification requiredPOST/v1/images/generationsImage generationPOST/v1/images/editsImage editing with a validated sourcePOST/v1/videosCreate a durable video jobGET/v1/videos/{id}Read job state and resultPOST/v1/audio/speechSpeech synthesisPOST/v1/audio/transcriptionsAudio transcriptionPOST/v1/filesOwner-scoped uploadGET/v1/artifacts/download/{token}Expiring owner-scoped artifact deliveryPOST/v1/realtime/callsNegotiate one WebRTC voice sessionDELETE/v1/realtime/sessions/{id}Release a sessionPOST/v1/embeddingsCreate indexed text vectorsPOST/v1/rerankRank supplied candidate documentsPOST/v1/structured-evaluationTyped answers from state and questions; renamed product routeGET/v1/modelsCaller-scoped model discoveryGET/v1/usageThe product owner’s usage; no shared provider balanceGET/calculate/modelsQuoteable rate specificationsGET/calculateQuote a bounded request shapePOST/dashboard/wallet/challengeCreate a wallet sign-in challengePOST/dashboard/wallet/verifyVerify a signed challengeGET/api/v1/payments/{quote_id}Owner-only inference and collection state, actual cost, receipt The structured-evaluation route is an explicit product naming change. The precise DTOs and headers remain implementation contracts to freeze with backend fixtures before enabling clients. ## Product identity and payment are separate Inference uses a scoped Noemad product API key or a supported playground session. The key belongs to the wallet account. It can restrict models, expiry, rate, and concurrency; it is not a provider key and does not authorize a token debit. ``` Authorization: Bearer NOEMAD_API_KEY Content-Type: application/json # Messages-compatible authentication, if supported by the frozen contract: x-api-key: NOEMAD_API_KEY ``` The intended wallet entry uses /dashboard/wallet/challenge and /dashboard/wallet/verify. Connection is followed by a server-verified challenge; the session must enforce origin, nonce, expiry, cookie security, and CSRF protection. ## Common and payment headers HeaderUseAuthorization / x-api-keyProduct authentication, according to the endpoint contractContent-TypeMatch JSON, multipart, SDP, or binary endpoint requirementsIdempotency-KeyOne key for one immutable logical mutationX-Request-IDA bounded caller correlation value; not proof of deduplicationPAYMENT-REQUIREDx402 payment requirements returned with HTTP 402PAYMENT-SIGNATUREClient authorization using the pinned x402 v2 upto schemaX-Quote-IDProduct extension binding retry to the immutable quoteRetry-AfterDelay before another eligible status check or safe retryX-Noemad-Request-IDProposed product correlation header; final spelling requires fixture agreementX-Noemad-Realtime-Control-TokenProposed session-release token header; keep it out of logs and URLs Generic SDKs do not automatically understand the quote extension. Use a payment-aware transport or local proxy owned by the user. Do not invent a payment signature format or silently sign on a user’s behalf. ## 402 → authorize maximum → deliver → settle actual Authenticate and validate the exact model, body, route, rate, and admission limits. Create a quote and return payment requirements before inference. The client checks the quote and obtains a bounded wallet authorization. Retry the same operation with the same quote, body, and authorization. The server binds the nonce once, then streams or returns the inference result. After reliable usage is final, calculate and collect the actual amount within the maximum. Read GET /api/v1/payments/{quote_id} for collection state and the verified receipt. The unused maximum remains in the wallet. Authorization does not transfer the maximum, reserve the wallet balance, or prove future collection will succeed. ## Inspect the full response lifecycle An error before response headers can use an HTTP error status. After a response begins, an error may arrive within an HTTP 200 stream. A buffered response can also contain an error body after initial whitespace. Always inspect the terminal payload. ProtocolTerminal failure referenceChat Completions SSEAn error object in a data frame; do not assume partial choices completedMessages SSEAn error event with the Messages error envelopeResponses SSEresponse.failed with response.error fieldsBuffered JSONA complete parsed result or an error envelopePayment collectionA separate owner-only status after inference; never inferred from stream success Do not insert product payment events into an established SSE protocol without an explicit compatibility design. A final settlement header cannot be added to already-sent HTTP headers. Partial tool arguments must never be executed. ## Error directory These codes retain the reference surface where applicable; the wallet/payment extension replaces prepaid-credit errors with explicit quote and collection states. Final mappings require endpoint fixtures. Check the machine-readable code and owner-scoped status instead of inferring a cause from a generic message. HTTPCodeAction400invalid_client_request_idCorrect the caller request ID.400invalid_fileValidate file bytes, encoding, size, and accepted type.400invalid_imageValidate image bytes, dimensions, and encoding.400invalid_reasoning_effortUse a level advertised by the selected model.400invalid_request_errorCorrect missing fields, invalid JSON, or invalid parameter values.400invalid_tool_historyMatch each tool result to its original tool-call ID.400output_token_limit_exceededLower the output cap before a new quote.400request_blocked_by_policyReview the request; repeated retries do not change a policy decision.400streaming_requiredUse a supported streaming transport with the same product payment rules.400unsupported_model_for_endpointChoose a model qualified for this endpoint.400unsupported_request_parameterRemove or correct the unsupported control.400unsupported_toolsUse a supported tool declaration or model.401invalid_api_keyCheck the product key; never substitute a provider credential.402payment_requiredReview the quote and authorization; a bearer key does not authorize spending.403key_expired / key_revokedRenew or replace the product key through the owner session.403permission_deniedCheck account role, model scope, and ownership.403entitlement_limitRespect the active per-request offer or account limit.404model_not_foundRefresh authenticated model discovery.413request_too_largeReduce the conversation or attachment size.422unsupported_input_modalityChoose a compatible model and payload.429client_error_cooldownWait and correct repeated invalid requests.429concurrency_limitWait for an active operation to finish.429image_requests_temporarily_limitedHonor the delay before another image operation.429ip_rate_limitReduce request frequency from the network.429model_rate_limitedWait before another request to that model.429rate_limitHonor Retry-After and the account or key limit.500internal_errorUse bounded backoff; preserve the quote and operation reference.500token_count_failedRecord the request ID and retry only when safe.502empty_model_responseNo usable output was returned; inspect the operation outcome.502invalid_model_responseDo not treat an unparsable response as success.502invalid_model_tool_argumentsNever execute incomplete or invalid tool arguments.502invalid_model_tool_callNever execute an undeclared tool.502request_processing_failedInspect owner-scoped operation state before another dispatch.502stream_interruptedPartial text or tool arguments remain incomplete.502tool_generation_limit_exceededDo not execute the incomplete action.503model_temporarily_unavailableUse bounded backoff; the code alone does not identify a cause.503service_busyHonor Retry-After and avoid duplicate operations.504generation_timeoutReconcile a possibly dispatched operation before creating another.504stream_idle_timeoutInspect the terminal outcome and any completed tool actions.504stream_time_limit_exceededTreat partial output according to the published delivery policy.504token_count_timeoutUse bounded backoff and retain correlation metadata. ## Retry and support information Correct input, identity, permission, scope, and policy failures before retrying. For transient failures, use bounded exponential backoff with jitter and honor a numeric Retry-After. Preserve quote, operation, and idempotency identity; do not create a second paid operation because the first timed out. Save the product request ID, endpoint, model, approximate time, and operation reference. Exclude credentials, raw payment signatures, and private session-control tokens from support messages and public logs. ## Ownership and asynchronous resources Files, jobs, sessions, results, and artifact grants belong to the authenticated product owner. Video uses a durable submit/poll lifecycle. Realtime uses one session across turns and requires explicit release. An expiring artifact URL is a delivery mechanism rather than permanent hosting. --- # Chat & text Compatible chat formats, model capabilities, reasoning, tools, and output. Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified. Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization. ## Choose the right request format EndpointPayload styleTypical use/v1/chat/completionsmessages, tools, streamChat history and broad compatible SDK support/v1/responsesinput, reasoning, toolsResponses clients and structured agent workflows/v1/messagessystem, messages, max_tokensMessages-compatible clients and content blocks All three retain their native success and error contracts. Payment authorization wraps the transport lifecycle; it does not require changing the model’s prompt into a proprietary single-input format. ## Chat Completions example ``` { "model": "MODEL_ID_FROM_DISCOVERY", "messages": [ { "role": "system", "content": "Return a concise, useful answer." }, { "role": "user", "content": "Summarize the design and list next steps." } ], "max_tokens": 1024, "thinking": "medium", "stream": true } ``` Send only controls advertised by the chosen model. The example reasoning level is a placeholder choice, not a universal supported value. The service must quote and enforce the actual output limit before dispatch. ## Responses example ``` { "model": "MODEL_ID_FROM_DISCOVERY", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Explain this design in three points." } ] } ], "max_output_tokens": 1024, "reasoning": { "effort": "medium" }, "stream": true } ``` Preserve response event ordering, content item IDs, final usage, and failure events. A client should not treat the first output delta as a completed response. ## Messages example ``` { "model": "MODEL_ID_FROM_DISCOVERY", "system": "Be concise and state uncertainty.", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Review this proposal." } ] } ], "max_tokens": 1024, "stream": true } ``` Messages content blocks and stop semantics must remain compatible. The server may accept the Messages authentication header where the final contract declares it. A separate token-count operation must be qualified before clients depend on it. ## Read capabilities instead of guessing Use input_modalities, context_length, max_output, and thinking from authenticated discovery. Text, image, video, and file input support vary even within one model family. Model-specific attachment limits and MIME requirements must also be enforced. The complete archived capability table and searchable model library preserve the source records. Their published maximums do not override Noemad’s admitted request limits. ## Reasoning controls auto delegates the choice only when supported. none disables reasoning only on models that advertise it. Levels such as minimal, low, medium, high, xhigh, and max are model-specific. A model with only auto should not show a runtime effort selector. The adapter maps product-compatible fields such as reasoning.effort or a thinking value into the native provider contract. Hidden reasoning tokens may affect usage differently from visible output; the quote must state the relevant limit and billing behavior. ## Tool definitions and complete history ``` { "tools": [ { "type": "function", "function": { "name": "lookup_note", "description": "Read a note the user has allowed this app to access.", "parameters": { "type": "object", "properties": { "note_id": { "type": "string" } }, "required": [ "note_id" ], "additionalProperties": false } } } ], "tool_choice": "auto" } ``` Tool declarations must match the endpoint format and selected model. A returned call must name a declared tool and contain complete schema-valid arguments. Match every tool result to its original call ID; preserve the original order and content blocks when continuing the conversation. The application, not the model, authorizes tool execution. Model output cannot increase a spending budget, change a payment recipient, or expand a tool’s data access. Parallel tool calls are permitted only when both model and application support them. ## Structured output and validation Where supported, schema-constrained text output can request a specific object shape. It is distinct from the dedicated typed evaluation endpoint. Pin the schema and model configuration, then validate the entire output. ``` { "title": "An illustrative summary", "summary": "A brief explanation of the proposal.", "actions": [ "Resolve the main open decision.", "Assign the next task." ] } ``` Reject empty content, unrecognized error envelopes, truncated JSON, invalid tool arguments, and forbidden finish reasons. A response succeeds only after its complete protocol and output contract are satisfied. ## Usage and payment outcome Record ordinary input, cached input, output, reasoning, or cache-write fields according to the model’s documented accounting. Do not double-count cached input already included in total input. Missing usage is unknown, not zero or the approved maximum. Inference completion and collection are separate. A usable partial stream can be billable under the pinned delivery policy, but it must have reliable attributable usage. An uncertain dispatch or usage outcome enters reconciliation rather than triggering a duplicate inference request. --- # Media Image, video, speech, transcription, files, and artifact delivery. Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified. Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization. ## Endpoint families CapabilityEndpointLifecycleImage generationPOST /v1/images/generationsSynchronous JSON or provider-supported streamImage editingPOST /v1/images/editsValidated source images and edit controlsVideoPOST /v1/videos · GET /v1/videos/{id}Durable job and pollingSpeechPOST /v1/audio/speechPlayable audio bytes or a verified artifactTranscriptionPOST /v1/audio/transcriptionsAudio upload to a complete transcriptFilesPOST /v1/filesOwner-scoped upload referenceArtifactsGET /v1/artifacts/download/{token}Scoped, expiring delivery grant Media controls are model-specific. An input file is not authorized merely because the UI can select it. The server validates content, size, ownership, supported types, and cost modifiers before admission. ## Image generation ``` { "model": "MODEL_ID_FROM_DISCOVERY", "prompt": "A marble observatory above an ancient Greek coastline.", "size": "1024x1024", "quality": "medium", "n": 1, "response_format": "b64_json" } ``` Only offer sizes, quality settings, counts, and response formats supported by the adapter. An image response may contain encoded bytes or an expiring URL. Check its actual MIME type and dimensions; the filename alone is not evidence. The archive distinguishes GPT image variants and two Imagine image versions. Some have separate quality, resolution, aspect-ratio, and editing controls. Those archived names do not imply that the corresponding route is enabled in Noemad. ## Image edits and uploads ``` POST /v1/images/edits Content-Type: multipart/form-data; boundary=BOUNDARY Idempotency-Key: SAME_LOGICAL_EDIT_KEY model = MODEL_ID_FROM_DISCOVERY prompt = Extend the courtyard, keeping the central statue. image = # Add size, mask, quality, or extra images only when supported. ``` Do not base64-wrap a file when the chosen endpoint requires multipart. Validate each source independently, apply count and resolution limits, and quote any extra-input surcharge. A retry keeps the same idempotency key and body. An upload returns an owner-scoped file ID only after acceptance. Map it to the provider reference on the server. Do not expose a shared provider file catalog or let one wallet retrieve another wallet’s files. ## Durable video jobs ``` { "model": "MODEL_ID_FROM_DISCOVERY", "prompt": "A slow camera orbit around a marble astronomical instrument.", "duration": 6, "resolution": "720p" } ``` ``` queued → running → succeeded ↘ failed ↘ unknown → reconcile Owner reads GET /v1/videos/{id} for the same durable job. ``` Persist the accepted job ID before polling. The create response may indicate that the job is still preparing or queued. Honor server polling guidance and stop when a terminal state is confirmed. A client reconnect or worker restart resumes the same job. An unknown create outcome is not permission to create another paid video. Publish cancellation and expiration semantics only once the adapter can prove them. A completed response must include verified duration, size, format, and a scoped result grant. Missing or invalid artifacts are not successful delivery merely because the provider job says completed. ## Speech synthesis and transcription ``` { "model": "MODEL_ID_FROM_DISCOVERY", "input": "Welcome to Noemad. Let us turn an idea into a result.", "voice": "VOICE_FROM_DISCOVERY", "response_format": "mp3" } ``` Speech synthesis validates text length, voice, language, speed or style controls, and output encoding. Stream or return audio only with the correct content type. A playable artifact and its delivered duration are part of the completion check. ``` POST /v1/audio/transcriptions Content-Type: multipart/form-data; boundary=BOUNDARY model = MODEL_ID_FROM_DISCOVERY file =