Model catalog, display names, pricing, and credit units (PR #46)
/oneaster/v1 APIs require a native login access_token (Authorization: Bearer $ONEASTER_ACCESS_TOKEN) and reject inference API Keys. GET /oneaster/v1/model-catalog lists catalog models and GET /oneaster/v1/model-catalog/detail?model=PUBLIC_NAME fetches a single model (URL-encode slashes). Each entry exposes both the callable model identifier model_name and the admin-editable display_name: UI cards may render display_name as a title, but inference requests must always pass model_name (or id from /v1/models) in the model field.
Prices are configured by administrators. Each model has pricing.mode: tiered_expr (billing_expr and billing_usage_schema), per_request (model_price), or ratio (model_ratio, completion_ratio, and related ratios). Group information group_ratio, usable_group, auto_groups, supported_endpoint, and pricing_version belongs to the catalog response data envelope, rather than a per-model group array. Combine the caller's group with the applicable billing mode; never hardcode prices or derive OneAster prices from vendor websites. official_price is an optional USD comparison baseline, null when unconfigured, and is never used in billing math or fabricated when absent.
Accounting units follow 1 USD = 100 OneAster credits; internal credit strings use 4 decimal places (for example "12.3450") while standard UI displays 2 decimal places. Native quota converts using quota_per_usd (1000000, so 1 OneAster credit = 10000 quota). Never mix upstream KIE points with OneAster credits or quota.
Account, wallet, and API Key management
GET /oneaster/v1/account reads the current account and GET /oneaster/v1/wallet reads wallet balance and spending. GET /oneaster/v1/keys accepts page, size, and keyword; GET /oneaster/v1/keys/{id} reads metadata; POST /oneaster/v1/keys creates an inference Key; PATCH and DELETE /oneaster/v1/keys/{id} update or delete it. Only creation returns the raw secret; if the creation response is lost, inspect existing Keys rather than automatically creating a duplicate.
Unified billing preview and top-up payments (PR #47 / #48)
The gateway provides a unified read-only credit preview endpoint:
GET /oneaster/v1/billing/preview?provider=stripe&amount_usd_cents=1000 Authorization: Bearer $ONEASTER_ACCESS_TOKEN
Unified preview requires a native login access_token or a PAT with wallet:read (rejects inference Keys) and returns Cache-Control: no-store. amount_usd_cents is a positive integer string in USD cents (e.g. 1000 = USD 10, not credits).
- Stripe: Amount must be an exact multiple of the active Stripe unit price and satisfy purchase limits (1 to 10000 units). Stripe rejects pay_currency and fee_mode.
- NOWPayments: Supports pay_currency (default usdttrc20) and fee_mode (deduct or on_top; default deduct). Amount range is subject to merchant settings (default USD 15–10000).
- Response fields: expected_credits, credits_per_usd: 100, credit_basis (purchased_quota for Stripe and NOWPayments on_top; net_settlement for NOWPayments deduct), fee_usd_cents: null, estimated_net_credits: null (unknown until settlement; never treat as 0), promotion_codes_enabled, discount_reason (no_discount or checkout_promotion_only), final_payment_amount_at_checkout: true, and checkout_request (passed directly into order creation).
- Legacy compatibility: GET /oneaster/v1/billing/stripe/preview?amount=10 remains supported (amount is integer purchase quantity).
- Preview is strictly read-only; it does not create orders, freeze funds, estimate unknown fees, or guarantee arrival.
Order creation and arrival records:
- Stripe orders: Use a login access_token or wallet:write PAT on POST /api/user/stripe/pay with amount and payment_method: "stripe", returning pay_link, trade_no, and real-time preview snapshot. Quoting can also use POST /api/user/stripe/preview. Creation failures may return HTTP 200 with message=error and error text in data, or success=false; inspect the native envelope and never automatically recreate an order.
- Stripe top-up records: User route GET /api/user/topup/self?p=1&page_size=20 (past 30 days); admin platform-wide route GET /api/user/topup?p=1&page_size=20. Items include expected_quota, expected_pay_usd_cents (original cents at creation), expected_credits, credited_quota, credited_credits, and credit_status (none, credited, or unknown). credited_credits appears only after the wallet credit transaction commits; uncompleted orders have "0.0000", and legacy successful orders without quota snapshots have null (never zero-filled or retroactively re-calculated). Browser return pages are not proof of arrival; check credit_status=credited before refreshing GET /oneaster/v1/wallet.
- NOWPayments orders: Check capabilities with GET /oneaster/v1/billing/nowpayments/capabilities, create orders via POST /oneaster/v1/billing/nowpayments/orders with a unique Idempotency-Key per intent, and inspect actual credited_credits and credit_status on GET /oneaster/v1/billing/nowpayments/orders/{id}.
Task billing diagnostics, registration barrier, and settlement receipts (PR #43 / #44)
Task generation success (status = SUCCESS) does not by itself prove that billing settlement is finalized. The gateway enforces a submission registration barrier (oneaster_task_registrations): if an upstream task is created but local pre-charge registration persistence fails, the gateway attempts to refund the pre-deducted quota, quarantines the task as status = UNKNOWN (reason_code = task_accounting_registration_failed), and returns 422 task_accounting_failed so background pollers cannot settle an unregistered task.
Users can call GET /oneaster/v1/task-diagnostics and GET /oneaster/v1/task-diagnostics/{task_id} to inspect their own task funding and billing evidence. List filters are page (1..10000), size (1..100, default 20), exception (all, exceptions, unknown, failed, stalled; default exceptions), task_id, stalled_seconds (60..86400, default 1800), start_timestamp, and end_timestamp (Unix seconds; default last 7 days). Admin lists at /oneaster/v1/admin/task-diagnostics additionally allow user_id and channel_id. Detail queries allow only stalled_seconds, plus user_id for admin details. Task diagnostics require a live login access_token and reject PATs and inference Keys; missing or foreign tasks on self routes return 404.
List items are lightweight summaries with billing_evaluated=false and top-level current_task_amount. Details include funding (source: wallet, subscription, unknown; credential_type: login_session, inference_key, unknown), billing (state: unknown, reserved, settled, released; finalized, observed_net_charge, original_reserved_amount, nullable settlement_receipt), evidence (up to 50 correlated logs, logs_truncated, aggregate_complete), reason_codes, automatic_retry_allowed=false, and reconciliation_review_url (only Root role >= 100 on KIE UNKNOWN tasks; otherwise null). current_task_amount remains top-level in details, outside billing. Render unconfirmed amounts as pending rather than zero; never auto-retry UNKNOWN or in-progress tasks.
curl --request GET "https://api.oneaster.ai/oneaster/v1/task-diagnostics/task_00000000-0000-4000-8000-000000000001" \ --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"
Request diagnostics and read-only troubleshooting CLI (PR #50 / #51)
GET /oneaster/v1/request-diagnostics/{request_id} reads the caller's evidence using native login credentials or a PAT with usage:read; it rejects username. GET /oneaster/v1/admin/request-diagnostics/{request_id} requires the native administrator role and, for PATs, log:read. Its optional username is an exact native username, not display_name: up to 64 UTF-8 bytes, with Unicode and internal spaces allowed, but no leading/trailing whitespace, controls, invalid Unicode, credential prefixes, or %. request_id is 1–64 letters, digits, underscores or hyphens; sk-, oak_, nap_ prefixes, wildcards, duplicate and extra parameters are rejected.
The {data: ...} envelope contains request_id, scope, user_id, observed_at (Unix seconds), total_records, truncated, records and billing. Records contain safe metadata, request_path, funding_source, and structured http_status/code/type/parameter_constraint; raw error bodies, conversations, files, IPs, Other, root/audit data, Keys and provider addresses are excluded. When visible to an administrator, routing includes attempts, channels, timing, status and decisions; self results have no administrator routing. routing_available=false means routing=[]; missing routing does not prove no upstream call. At most 100 routing entries are returned with routing_truncated. parameter_constraint extracts only specific integer minimum errors for max_tokens, max_completion_tokens and max_output_tokens. minimum:16, received:1 is example evidence, not a universal model limit; arbitrary upstream errors may not parse.
One native read contains at most 100 logs; pages are not combined into a confirmed snapshot. billing.consume_count/refund_count count records read. observed_net_charge is the observable consume-minus-refund log amount: quota is an integer string, credits a four-decimal string. Without financial logs the amount is null; self truncation gives aggregate_complete=false and an unknown amount. Negative financial quota within int64 makes the aggregate unknown; missing required quota, overflow or malformed structure returns 502. Null is not free, zero charge, or proof of unchanged wallet. Request diagnostics always have billing.finalized=false and are neither settlement receipts nor wallet balances; inspect task diagnostic details for the completion receipt and full correlated financial evidence. logs_truncated alone does not mean the financial aggregate is incomplete; inspect aggregate_complete separately.
Example (set the environment variable to your authorized native credential first; do not store it in code or logs):
curl --request GET 'https://api.oneaster.ai/oneaster/v1/request-diagnostics/REQUEST_ID' \ --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"
No visible records returns 404 request_diagnostic_not_found. Multiple visible owners sharing an ID or a truncated admin read returns 409 request_diagnostic_ambiguous. Exact username can narrow the search, but historical usernames can be reused; a still-truncated result remains 409 and is not automatically merged.
Run these commands at the oneaster-gateway repository root, not oneaster-doc or the old Core oneaster-admin. The token file must be a user-owned regular non-symlink file with no group or other access; 0600 is recommended. Paths and IDs are placeholders.
export ONEASTER_GATEWAY_URL='https://api.oneaster.ai' ONEASTER_TOKEN_FILE='/path/to/private/native-token-file' npm run admin --prefix oneaster -- requests get REQUEST_ID --token-file "$ONEASTER_TOKEN_FILE" npm run admin --prefix oneaster -- requests get REQUEST_ID --admin --username USERNAME --token-file "$ONEASTER_TOKEN_FILE" npm run admin --prefix oneaster -- task-diagnostics list --admin --exception failed --token-file "$ONEASTER_TOKEN_FILE" npm run admin --prefix oneaster -- task-diagnostics get TASK_ID --admin --user-id 6 --token-file "$ONEASTER_TOKEN_FILE" npm run admin --prefix oneaster -- channel-health get --window-seconds 3600 --limit 100 --channel-limit 100 --token-file "$ONEASTER_TOKEN_FILE"
Self logs and request diagnostics require native identity and usage:read for PATs; admin logs and requests require a native admin role and log:read for PATs. Self and admin task diagnostics require a valid native login session and reject PATs. Channel health requires a native admin role and both channel:read and log:read for PATs. Scopes do not elevate roles; inference sk- Keys cannot authenticate these commands.
Only logs list/stat --admin accept username/channel; admin requests get accepts only exact username. Task list accepts page, size, exception (all/exceptions/unknown/failed/stalled; default exceptions), task_id, stalled_seconds, start_timestamp, end_timestamp, plus user_id/channel_id for admins. Get accepts only stalled_seconds and admin user_id. Task IDs are 1–191 letters, digits, underscores or hyphens; windows are at most seven days; stalled_seconds is 60–86400 (default 1800), page defaults to 1 and size to 20. --admin is a standalone boolean flag.
channel-health get calls the existing GET /oneaster/v1/admin/channel-health: window_seconds 60–86400 defaults to 3600, limit and channel_limit each 1–100 default to 100. It accepts no channel ID, --admin or write flags. Preserve the distinct meanings of channel.status, evidence.state, backup_presence, coverage and their truncation/completeness fields. This is passive observation of configuration and historical type 2/type 5 logs, not a live provider probe; historical success and configured backups do not establish current availability. The projection excludes provider addresses, channel Keys, raw errors and conversations, and fails on malformed responses rather than inventing health.
These added diagnostic commands use GET only and accept no body, --yes, paid test, repair or automatic retry flag. They do not retry or change channels or wallets. --dry-run validates local syntax and shows the target GET path without credentials or network; it does not verify server permissions or business rules. Exit codes: success 0, local parameter error 2, 401/403 3, 409 4, 404/transport/other errors 1. Errors do not echo raw responses.
Admin passive channel health, pricing issues, and multi-key recovery (PR #40 / #41 / #46)
Administrator endpoints require administrator credentials, are excluded from the public API Key Playground, and must not expose channel_id or upstream secrets in end-user views.
GET /oneaster/v1/admin/channel-health (window_seconds 60..86400 default 3600, limit 1..100 default 100, channel_limit 1..100 default 100) requires a live admin role (>= 10), channel read permission, and (when using a PAT) channel:read + log:read scopes. It performs a passive read-only aggregation of channel config, model routing, consume logs (type=2), and error logs (type=5, recorded when ERROR_LOG_ENABLED=true). It never sends live paid probes to upstream providers, and channel.status is enabled, manually_disabled, or auto_disabled; evidence.state is unknown, observed_success, observed_failure, or mixed; model-group backup_presence is configured, not_configured, or unknown. These observations do not guarantee uptime or failover. Responses stay under 1 MiB; truncation flags live in coverage (including channels/success/failure.truncated, models_truncated, and output_truncated). Also inspect route_counts_complete and evidence_complete.
GET /oneaster/v1/admin/pricing/issues requires Root administrator access (role >= 100) and checks active models across enabled channels and model_name_mapping aliases for unconfigured, incompatible, and stale pricing rules. In addition, PR #46 wraps multi-key channel enable_key / enable_all_keys operations in a database transaction and auto-restores a disabled channel only when disabled_reason is all_keys_disabled, preserving manual admin disablement.
Playground generation history and capability bindings
GET /pg/generations lists the current user's Playground history; GET /pg/generations/{generation_id} reads details; GET or HEAD /pg/generations/{generation_id}/assets/{asset_key}/content reads an artifact. All require a live native login session explicitly sent as Authorization: Bearer <login-session-token>. A PAT, inference key, or another user's session cannot substitute. Browser requests with Origin must pass the /pg origin check; native HTTP clients may omit Origin. Missing and other users' records return 404, including for administrator sessions.
List, detail, and content each require exactly one model, kind, and source: model is the public model ID used for the request, kind is image, video, or audio, and source is playground. The model must be valid UTF-8, 1–255 bytes, without leading or trailing whitespace, control characters, or ? # [ ] \; slash-separated segments cannot be empty or equal to a single or double dot. URL-encode query values. The list additionally accepts limit (canonical decimal integer 1–50, default 20) and cursor. A cursor is bound to the account, model, and kind; reuse it unchanged within that scope. Detail and content reject limit and cursor; all reject duplicate and extra query parameters. generation_id is 1–64 ASCII letters, digits, underscores, or hyphens.
GET /pg/generations?model=<URL-encoded-public-model-ID>&kind=image&source=playground&limit=20 Authorization: Bearer <login-session-token>
The list returns items and nullable next_cursor. Records include id, request_id, model, kind, source, operation, status, created_at, updated_at, nullable task_id, artifacts, and nullable failure; detail also returns input. No input archive currently exists: input_available=false, input and prompt_excerpt are null. Do not reconstruct prompts, uploads, or replay requests from history. Reading history neither precharges again nor calls the provider. Even after a synchronous task's task.data is discarded, an intact unexpired intent response may still provide its image; task and provider expiry also constrain availability.
Invalid queries return 400 invalid_generation_query; storage or artifact projection failures return 503 and must not be shown as an empty list. Content returns 409 generation_not_ready while incomplete, 410 generation_asset_expired when expired, and 404 for absent or inaccessible records. Image artifacts may include delivery: {url, hosts}: a constrained client-BFF read declaration for an HTTPS CDN declared by the executing plugin, without port, user info, fragment, request credentials, or body. Strip delivery from browser metadata; it is not an anonymous download or arbitrary URL proxy. The protected content_url is the history file endpoint.
GET /api/oneaster/generation-bindings returns public-model generation bindings filtered by usable groups for display and integration. It follows native pricing navigation permissions: anonymous access is possible when enabled without required login; user authentication is required when configured; when disabled, ordinary access is denied and an authenticated Root may access under native rules. Verify the deployment configuration. Public model ID, plugin key, upstream model, and display_name serve different purposes. Bindings describe metadata; they do not prove successful plugin execution, model enablement, pricing, or an available route.
Read generated resources from request logs
Entries from GET /oneaster/v1/logs and GET /oneaster/v1/admin/logs include nullable task_id and resource_lookup. Associate resources using request_id, not the displayed log sequence number. Charge, refund, and adjustment logs for one task can point to the same output and are not separate generations. task_id is the single currently known task and may be null when multiple tasks are known; see detail task_ids for the full set. resource_lookup.state resolvable means a lookup clue exists, unknown means not confirmed, and not_applicable means explicitly inapplicable; none guarantees completion or permanent availability. href can be null.
User detail is GET /oneaster/v1/logs/requests/{request_id}/resources; user content is GET or HEAD /oneaster/v1/logs/requests/{request_id}/resources/{resource_id}/content. Administrators use /oneaster/v1/admin/logs/requests/{request_id}/resources and its /{resource_id}/content child, both with exactly one user_id=<log-owner-ID>, not the administrator's own ID. User routes accept no query parameters; admin routes reject duplicates and extras. user_id is a positive decimal safe integer of at most 16 digits without leading zeros. request_id is 1–64 ASCII letters, digits, underscores, or hyphens and cannot start with sk-, oak_, or nap_ (case-insensitive); resource_id is 64 lowercase hexadecimal characters. Invalid identifiers or parameters return 400 invalid_resource_query.
GET /oneaster/v1/admin/logs/requests/<request-ID>/resources?user_id=<log-owner-ID> Authorization: Bearer <administrator-login-session-token>
Detail data contains request_id, task_ids, state, reason, and an items array; state is ready, pending, failed, or unavailable. Possible reasons include expired, not_retained, unsupported_source, plugin_unavailable, missing_evidence, snapshot_lookup_unconfigured, and generation_failed. Preserve the actual reason; do not automatically archive or regenerate. Items contain resource_id, nullable task_id, source, type, mime_type, filename, size_bytes, expires_at, and relative content_url. Unknown size or expiry is null; handle multiple files as an array. The protected content_url is neither an anonymous capability nor a provider URL.
Detail and content require a live native login session; administrators also need an enabled account and actual administrator role 10 or 100. PATs and inference keys cannot substitute. Absent or other-owner resources return 404; incomplete or ambiguous evidence returns 409. Do not hide storage failure as an empty result. Authorization is checked again before transmission. Content returns 200 for a complete read, 206 for a valid single Range, 416 for an unsatisfiable range, 409 when pending, 410 when expired, and 429 when download concurrency is busy; invalid or multiple ranges return 400. Preserve actual MIME, Content-Length, Content-Range, Accept-Ranges, safe Content-Disposition, Cache-Control: private, no-store, and X-Content-Type-Options: nosniff.
A browser should use its same-origin BFF to forward the user's Authorization: Bearer <login-session-token>; never put tokens in URLs. Cross-origin img/video URLs do not automatically carry Bearer. Images can use an authenticated fetch and Blob URL; stream video and audio through the BFF, forwarding GET, HEAD, Range, and If-Range. Downloads are limited to 512 MiB and 120 seconds, with at most 8 concurrent downloads per process and 2 per actor; native gateway or proxy limits may be stricter.
Native task artifacts and retained Playground synchronous images, non-streaming audio, and transcription/translation text are supported. Synchronous snapshots are retained for at most 24 hours and 4 MiB. A user's URL-based synchronous image is read through native ownership checks; cross-user administrators cannot use that source. Unsaved ordinary /v1 synchronous responses, some artifacts available only at old external URLs, and expired or unretained snapshots cannot be recovered this way. If the optional read-only views and ONEASTER_LOG_RESOURCES_POSTGRES_DSN are not configured, tasks with task_id in public logs may still be queried, while synchronous snapshots and tasks linked only through private evidence may be unavailable. List storage failures can degrade to unknown; an active detail lookup returns a sanitized 503 on storage failure. Configuration and production availability require verification and do not imply a permanent archive.
Secure channel configuration and model updates
The channel facade forwards the caller's own native Bearer identity and enforces the live native administrator role and permissions on each call. It does not use a shared Root credential. Permissions and PAT scopes are separate constraints: a PAT cannot elevate the account's role or permissions, and an inference Key is not a management credential. Listing, detail, types, and config reads require channel.read; creation requires channel.sensitive_write; ordinary updates and upstream-apply require channel.write; sensitive changes such as Key, base_url, or overrides also require channel.sensitive_write. Testing, status changes, discover-models, and upstream-detect require channel.operate; plugin options and bindings require task_plugin.bind. Operations that read a channel before writing or read it back also require channel.read. A PAT additionally needs the scopes for each actual native call, such as channel:read, channel:write, channel:operate, channel:sensitive_write, or task_plugin:bind. A scope does not replace the permission check.
- GET /oneaster/v1/admin/channels/types lists local types and safe default addresses (unsafe addresses become null); it does not test connectivity.
- GET /oneaster/v1/admin/channels/plugin-options returns key, name, models, and new_api from the local registry. new_api indicates local support for that upstream kind, not that an upstream has installed the plugin.
- GET /oneaster/v1/admin/channels/{id}/config returns the safe channel, setting, settings, header_names, and param_override_present projection. Raw credentials, arbitrary native JSON, and header values are not returned; unsafe or unparseable stored configuration fails. Native plaintext channel Key disclosure is a separate high-risk operation requiring Root and a single-use security proof scoped to channel.key.read and bound to channel_id; the configuration projection does not expose it.
- PATCH /oneaster/v1/admin/channels/{id}/config accepts a nonempty subset of the channel, setting, settings, headers, and params allowlists; omitted fields are retained. setting permits pass_through_body_enabled, responses_websocket_enabled, task_plugin_key, and task_extend_plugin_keys; settings permits upstream_model_update_check_enabled and upstream_model_update_auto_sync_enabled. Native plugin-binding authorization still applies.
- headers and params each use {"set":{...},"remove":[...]}. Allowed header names are accept, content-type, user-agent, x-request-id, x-client-version, anthropic-version, anthropic-beta, and openai-beta; values are write-only. params accepts safe names and flat scalar values. Unknown and complex stored entries are preserved but cannot be directly inspected or edited. Key replacement on an existing multi-Key channel is unavailable; ordinary edits preserve multi-Key information. Updates cannot clear models; native pointer string fields can be cleared with an empty string.
- POST /oneaster/v1/admin/channels/{id}/discover-models takes {} and contacts the saved channel's upstream only when explicitly called. It returns models without saving them.
- POST /oneaster/v1/admin/channels/{id}/upstream-detect takes {} and returns add_models, remove_models, and last_check_time. The native handler persists the detection but does not automatically apply it.
- POST /oneaster/v1/admin/channels/{id}/upstream-apply takes optional add_models, remove_models, and ignore_models arrays and changes channel model configuration. detect/apply return 409 for incompatible or unknown stored settings to avoid discarding them through the native fixed structure.
POST /oneaster/v1/admin/channels creates one channel and requires type, name, key, models, and group; type 61 also needs a valid setting.task_plugin_key. The existing PATCH /oneaster/v1/admin/channels/{id} rejects raw configuration fields and setting/settings; use config for structured edits. Change status with POST /oneaster/v1/admin/channels/{id}/status and status 1 or 2. A list filtered by keyword, model, or tag scans at most 1,000 rows: excess returns 422 channel_search_limit and an inconsistent scan returns 409 channel_search_changed. keyword matches name or exact ID, never a Key or URL; tag is exact. total and type_counts describe the filtered scan, not system-wide health.
Native read-merge-write has no CAS or cross-instance atomic conflict protection; coordinate concurrent operators and reread. Native HTTP 200 success=false during creation, configuration, status, detect, or apply may follow a partial write, and the facade may return 409 channel_result_unknown. A disconnect, timeout, or failed readback also does not prove that nothing was saved. Reread and inspect manually before deciding what to do; do not automatically retry writes. A genuine native 403 remains a permission denial; do not infer 403 from business-error text.
Stripe risk and security behavior
GET /oneaster/v1/admin/stripe/risks and the backend repository CLI's stripe-risks list accept only a valid native Root login session; ordinary administrators, PATs, and inference Keys are rejected. This read-only projection returns at most the latest 100 entries with scope recent_up_to_100. user_id=0 means unassociated and resolved_at=0 means that individual entry is unresolved. An empty list or one resolved entry does not prove all risks are resolved. The CLI does not query Stripe or resolve risks and omits reason, amounts, and a full total; --dry-run reads no credentials and makes no network request.
Native GET /api/stripe/risks includes reason. The high-risk POST /api/stripe/risks/{event_id}/resolve separately requires a valid Root session and X-Security-Proof. First obtain available methods from GET /api/verify/methods?scope=stripe.risk.resolve and reauthenticate using the applicable MFA flow. The proof uses scope stripe.risk.resolve and context binding the same event_id and reason; the JSON request reason must match, be nonempty, and be at most 500 bytes. The proof is session-bound and single-use; password cannot bypass enabled MFA. After a lock timeout or storage failure, check the state and reauthenticate; never automatically replay the proof. Other unresolved events can continue the hold.
An associated unresolved refund or dispute can cause new paid inference to return 403 payment_risk_hold; unavailable risk storage returns 503. The account can still log in, check its balance, and contact support. The risk check does not directly debit the wallet or revoke existing financial evidence, and already accepted in-flight tasks settle under their existing accounting rules. FreeModel is identified by native administrator pricing and configuration; zero pre-consumption does not guarantee the entire request is free.
Webhook processing associates payments and risk events through Checkout, invoice, subscription, and PaymentIntent records; a late payment event can associate a previously unassociated risk. An initial subscription payment lacking necessary association remains pending. Valid promotion codes do not change purchased credits; actual payment is determined at checkout and must not be rejected solely for differing from the original price. Native preview or order creation can report a business failure with HTTP 200, so inspect the response envelope. These are source behaviors, not evidence that production Webhook configuration, a real dispute, or supplier integration has been accepted.
MiniMax image and speech tasks
In the pinned source, the plugin keys are `minimax-image` and `minimax-speech`; their declared upstream models are `MiniMax-H3-Image` and `speech-2.8-hd`, respectively. These declarations do not establish that a production catalog, channel, or price is enabled. Set `model` to the administrator-configured public callable ID; it is distinct from the plugin key, upstream model, and display name. All examples use placeholders and do not claim an accepted live call.
With an inference Key, submit to `POST /v1/tasks/minimax-image` or `POST /v1/tasks/minimax-speech`. The wallet equivalents are `POST /pg/tasks/minimax-image` and `POST /pg/tasks/minimax-speech`, authenticated with the caller's valid native login access_token, not a PAT or inference Key. Browser `/pg` requests must also satisfy trusted Origin checks. Generate and retain an `Idempotency-Key` for a new intent; after a disconnect recover the original intent rather than automatically creating another task. Both surfaces require a usable model binding, channel, and administrator price. A plugin metadata route alone is not evidence of a public gateway route, and these plugins are not necessarily equivalent to the OpenAI synchronous image or audio APIs.
Image task JSON example:
{"model":"YOUR_PUBLIC_IMAGE_MODEL_ID","prompt":"A small paper boat","n":1,"resolution":"1K","aspect_ratio":"1:1"}
The image `prompt` must be nonblank and at most 32000 Unicode characters; `n` is 1–10, default 1. `resolution` (or its alias `area`) is `1K`, `2K`, or `4K`, default `1K`; if both are supplied they must match. `aspect_ratio` is one of `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `9:21`, `3:2`, `2:3`, default `1:1`. `response_format` may be `url` or `b64_json`, but the plugin requests URL and PNG upstream; this does not guarantee base64 output. `stream` may be omitted or false. Reference images, image editing, and other unspecified fields are not accepted by the current validator.
Speech task JSON example:
{"model":"YOUR_PUBLIC_SPEECH_MODEL_ID","prompt":"Hello from OneAster.","audio":{"mode":"speech","voice":"male-qn-qingse"}}
The speech `prompt` must be nonblank and at most 9999 Unicode characters. `audio.mode` must be `speech`; `male-qn-qingse` is currently the only supported `voice` and is the default. `instructions` cannot contain nonblank free-form style instructions; extra audio settings and output-format parameters are rejected. The plugin requests a non-streaming URL and MP3 output (32 kHz, 128 kbps, mono).
Save the gateway `task_id` from submission. Query `GET /v1/tasks/{task_id}` or `GET /pg/tasks/{task_id}` on the same surface, then `GET .../artifacts` and use the returned public `key` and `content_url` for `GET` or `HEAD` content. Image keys are `image-1`, `image-2`, and so on; the speech key is `speech`. Do not substitute a supplier ID. `/v1` task reads use an inference Key; `/pg` reads require the owner's valid login Bearer. Send authorization when fetching protected content and never put the Bearer in a URL. These plugins make synchronous supplier calls but record gateway tasks; results remain subject to retention and expiry. `FAILURE`, `UNKNOWN`, or disconnection does not establish that an automatic new generation is safe.
Image quantity and settlement
`n` is a requested quantity, not a guarantee of the number of artifacts. Supported image paths update settlement with the actual count when valid output can be established, including partial results or more results than requested. The MiniMax plugin counts valid HTTPS image results and requires supplier `generated_images` usage to match; missing or inconsistent usage is not confirmed settlement. Ordinary OpenAI-format image responses count nonempty `url` or `b64_json` payloads; when no count can be established the requested count is retained, so an empty response must not be assumed free. A normally completed image stream can reduce the count based on completed events; a client disconnect cannot reduce it that way, although a higher observed count can increase it. Failure, release of reservations, and async settlement differences follow the applicable native accounting rules and evidence; do not assume every failure is fully refunded. Tasks and artifacts are not retained forever. Consult wallet, logs, and task settlement evidence rather than calculating a charge in the client; administrators set prices and group multipliers.
Key budgets
On Key creation, omit `budget_credits`, use null, or use an empty string for unlimited budget. A finite budget must be positive, exactly representable in native quota, use at most four decimal places, and respect the native maximum. The creation budget may exceed the wallet balance: it adds no wallet funds and does not guarantee sufficient funds at call time. Wallet, Key status, model, and channel rules still apply. Updating a Key has separate checks: changing a finite total budget can return `key_budget_exceeds_wallet` if it exceeds the available wallet or `key_budget_below_spent` if below lifetime spending. Do not apply the creation rule to updates. An unlimited Key budget does not imply an unlimited wallet.
Read-only backend diagnostic CLI
Run these commands from the **oneaster-gateway backend repository**, with Node.js 24+, `ONEASTER_GATEWAY_URL`, and `--token-file` pointing to the caller's native login credential file. All paths below are placeholders. The file must be owned by the caller, mode 0600, and not a symbolic link. Support and Stripe risk commands reject PATs and inference Keys; the CLI does not perform login or MFA.
export ONEASTER_GATEWAY_URL="https://YOUR_GATEWAY_HOST" TICKET_ID="00000000-0000-4000-8000-000000000001" # replace with your ticket ID npm run admin --prefix oneaster -- support capabilities --token-file /path/to/SESSION_TOKEN_FILE npm run admin --prefix oneaster -- support list --token-file /path/to/SESSION_TOKEN_FILE npm run admin --prefix oneaster -- support get "$TICKET_ID" --token-file /path/to/SESSION_TOKEN_FILE npm run admin --prefix oneaster -- support messages "$TICKET_ID" --include-content --token-file /path/to/SESSION_TOKEN_FILE npm run admin --prefix oneaster -- stripe-risks list --token-file /path/to/ROOT_SESSION_TOKEN_FILE
`support` reads the caller's tickets by default. `capabilities` does not accept `--admin`; `list`, `get`, and `messages` support `--admin` for an authorized administrator, while `--user-id` applies only to admin `list`. `list` supports `--page`, `--size`, `--status`, and `--type`; `messages` supports `--page`, `--size`, and `--include-content`. Message bodies are hidden by default and remain filtered when explicitly included. Attachment metadata is returned, but attachments are not downloaded. Commands do not auto-page, retry, or write tickets; `--dry-run` validates local syntax and paths only.
`stripe-risks list` requires a valid native Root session and reads at most the most recent 100 records. It does not contact Stripe, resolve risk, or output reasons, amounts, or a full-database total. An empty sample does not prove the entire system has no risk. For an individual record `resolved_at=0` means unresolved and `user_id=0` means no associated user.
Settings persistence and operations
For an ordinary single-key `PUT /api/option/`, the database write and commit are confirmed before publication in the local process. A database failure returns the existing error envelope and does not publish the proposed value. A lost response or connection during commit can leave the result uncertain: inspect durable state before deciding whether to retry. Secret fields may be absent from the read response. Ordering applies to relevant writes and refreshes in one process; other instances can refresh later. Some legacy validation paths can fail runtime parsing or partially publish after persistence, so not every error proves that nothing was saved.
KIE balance and Feishu alerts are a separate operations worker, with monitoring and delivery disabled by default. Source availability does not prove deployment enablement, connectivity, or delivery. KIE credits differ from OneAster wallet credits; do not replace an unknown balance with zero. No failure samples or a recovered balance does not establish real-time model availability. The worker adds no public HTTP API.
Retry and DeepSeek compatibility
Continue using `POST /v1/chat/completions` for standard chat. The internal request-body retry fix requires no special client header and does not make every request safe to retry automatically. If the result is uncertain, inspect existing request or task evidence to avoid duplicate billable generation. For Chat Completions routed through the DeepSeek adapter, `developer` message roles are converted to `system` before sending upstream. This is adapter-specific compatibility, not a universal role rule for all models or the Responses protocol.