Managed AI Models and Pricing

Open4X-managed services use platform-owned upstream credentials. Merchants use their own Open4X keys. Existing BYOK instances retain their existing behavior and fees.

Availability

This feature requires migration 0057_managed_ai.sql and matching gateway, operations and merchant console releases. A code or documentation release does not mean an environment has enabled models. Check its model catalog. The first adapter supports OpenAI-compatible text chat, SSE chat and text embeddings only, not Jev, tools, images, audio or arbitrary request transformations.

Operations Setup

Open Operations → AI services. platform_admin can modify configuration; finance is read-only. Tenant administrators cannot access platform costs or credentials.

1. Add an Upstream with its direct HTTPS Base URL, Bearer or X-API-Key credential, timeout and concurrency limit. The adapter appends /chat/completions, /embeddings and /models. Do not point it back at the Open4X gateway.
2. Add a draft in Models & prices with a public alias, upstream model ID, capabilities and input/output token ceilings.
3. Publish price: enter USD selling and provider-cost rates for input, output, cached input per million tokens, plus a per-request fee. Below-cost prices require explicit confirmation. Activate the model after publishing its price.
4. Customer offers: select the billing account ID and model. Choose a percentage (80 means 20% off) or contract rates, with UTC start/expiry times. For team workspaces, use the billing owner ID, not a support agent ID.

Keys are AES-GCM encrypted and never returned, including ciphertext. Leaving the replacement key blank preserves it. Changing the upstream URL requires re-entering the key. Connection testing checks /models HTTP reachability/authentication without generating content; it is not an inference acceptance test. Tests are disabled when external side effects are disabled.

Changing a model's upstream or upstream model name requires saving it as draft/inactive, publishing a new reviewed price, then reactivating it. Historical price versions and in-flight request snapshots are preserved.

Merchant Integration

In Services, create an AI Model Gateway instance with Open4X managed billing. Select a model and inspect your effective prices.

{
  "service_id": "ai-model",
  "alias": "assistant",
  "config": { "mode": "managed", "model_alias": "standard-chat", "max_cost_per_request": 0.05 }
}

Submit to POST /console/services with a merchant login and service:manage permission. Platform models must be active and priced. Upstream credentials/URLs sent by the merchant are not retained in managed configuration.

Create an API key with ai:invoke, restricted to ai-model:assistant. Keep it on your server, never in a browser or Widget.

curl https://api.open4x.com/v1/apps/ai/assistant/v1/chat/completions \
  -H "Authorization: Bearer $OPEN4X_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-business-request-id" \
  -d '{"model":"standard-chat","messages":[{"role":"user","content":"Hello"}],"max_tokens":512}'

Omit model or use the configured public alias; arbitrary upstream models are rejected. Add stream:true for SSE. Use /v1/apps/ai/assistant/v1/embeddings with text input for embeddings-enabled models.

Billing Contract

• USD only. Cached input is a subset of input tokens and is not charged twice.
• One current offer per customer/model: contract prices replace list rates; percentage discounts apply to all four selling rates. Offers do not stack. Expired, future or inactive offers are ignored.
• Each request snapshots its immutable price version, provider-cost rates and offer version. Later edits do not alter in-flight or historical bills.
• Integer arithmetic is used, then each final customer charge is rounded upward to the existing ledger quantum of USD 0.0001. Very small nonzero requests can therefore cost USD 0.0001. Explicit free rates or a zero multiplier produce zero charges.
• Provider costs are configured estimates, not reconciled supplier invoices.

Before contacting a provider, the gateway reserves the cost of the model's entire configured input ceiling plus the requested output limit. Both service and request budget caps apply. 402 means insufficient available balance, 409 can mean the reservation exceeds a cap, and neither invokes the provider.

The JSON request byte limit is four times the configured input token ceiling, not an exact tokenizer check; the provider may still reject oversized context. Measured usage settles the request and releases the remainder. Provider failures, invalid responses and interrupted streams release the reservation. Missing usage or a measured price above the reservation releases the full hold and records review, rather than charging an estimate. Verify provider usage reporting and SSE final usage plus [DONE] before commercial activation.

Settlement failures retain the hold for review. Administrators can release expired or review holds with an audit reason in Usage & settlement. Live reservations cannot be manually released. Repeated release does not refund twice. Automatic retroactive collection is not implemented.

Repeated Idempotency-Key returns 409 without another call/charge. This is duplicate prevention, not response caching. Inspect request records before retrying an uncertain result with a new key. There is no automatic cross-provider fallback in this initial adapter.

Timeout is a total request deadline of 1–120 seconds, including streaming. Upstream concurrency is enforced atomically via database reservations; exhaustion returns 429. Existing API-key source/rate/daily policies still apply. Staging/test environments prohibit real AI calls by default.

Queries and Records

Endpoint	Purpose
GET /console/services/managed-ai/models	Your effective model prices, without provider costs or secrets
GET /console/services/managed-ai/usage	Your latest 100 request/settlement records
GET /ops/ai/models/:alias/prices	Latest 100 immutable price versions
GET /ops/ai/requests	Latest 200 platform request settlements and estimated costs
GET /ops/audit-logs	Configuration, rotation, price and reservation-release audit

reserved_units and final_units use USD 0.0001 units; null final units means unsettled. Responses include X-Request-ID, X-Open4X-Price-Version, and X-OpenEdge-Estimated-Cost. JSON responses also include X-OpenEdge-Final-Cost; query records for final SSE charges. Billing records do not persist prompts or responses. Self-hosted inference still receives necessary inputs from the cloud gateway.

These first-version lists have explicit row limits; large-history export is not included. Download the management OpenAPI.

AI Integration Review Prompt

Review this project's Open4X managed AI integration without printing secrets.
Verify mode=managed and a catalog model_alias; keep ai:invoke keys server-side and restrict service_aliases to ai-model:<instance alias>.
Use the public model alias; do not send tools, images or unsupported parameters.
Check reservation budgets, actual usage, cached-input accounting, immutable pricing, nonstacking discounts and upward USD 0.0001 rounding.
Test SSE completion/cancellation, 402, 409, 429 and 5xx. Do not change Idempotency-Key automatically after uncertain results. Surface review/settlement errors.
Keep human chat working when AI fails. Report evidence and gaps; do not modify live prices, balances or credentials.