Canonical API contract
LLM Proxy HTTP API
The sole canonical wire contract for llm-proxy-owned proxy, browser configuration, and management endpoints. Each configured text model owns one explicit upstream wire contract and execution lifecycle. OpenAI Responses and Gemini 3.x Interactions use stored pollable resources; Gemini 2.5 Interactions, OpenAI-compatible Chat Completions, and Anthropic Messages complete synchronously. Public proxy operations remain blocking and never expose an upstream resource id. OpenAI resource ids remain in memory only, but the current adapter does not cancel or delete stored Responses, so OpenAI account retention policy applies. Background Gemini interaction ids are also request-local; the adapter cancels active resources and deletes every stored interaction on exit. Synchronous Gemini interactions are non-stored. TAuth-owned endpoints are outside this contract. Contributors must update this document in the same change as any owned handler or bundled-client wire change.
OpenAPI YAML
The complete canonical manifest is shown below. The download action publishes these exact source bytes.
openapi: 3.1.0
info:
title: LLM Proxy HTTP API
version: 1.0.0
description: >-
The sole canonical wire contract for llm-proxy-owned proxy, browser
configuration, and management endpoints. Each configured text model owns
one explicit upstream wire contract and execution lifecycle. OpenAI
Responses and Gemini 3.x Interactions use stored pollable resources;
Gemini 2.5 Interactions, OpenAI-compatible Chat Completions, and Anthropic
Messages complete synchronously. Public proxy operations remain blocking and never expose an
upstream resource id. OpenAI resource ids remain in memory only, but the
current adapter does not cancel or delete stored Responses, so OpenAI
account retention policy applies. Background Gemini interaction ids are
also request-local; the adapter cancels active resources and deletes every
stored interaction on exit. Synchronous Gemini interactions are non-stored.
TAuth-owned endpoints are outside this contract.
Contributors must update this document in the same change as any owned
handler or bundled-client wire change.
servers:
- url: https://llm-proxy-api.mprlab.com
description: Production API origin
x-llm-proxy-protocol-methods:
- OPTIONS
tags:
- name: Proxy
description: Tenant-key-authenticated text and dictation operations.
- name: Configuration
description: Public browser runtime configuration owned by llm-proxy.
- name: Capabilities
description: Public provider, model, capability, and request-limit resources.
- name: Management
description: TAuth-session-authenticated tenant management operations.
paths:
/:
get:
operationId: getText
summary: Generate text from a query prompt
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Prompt'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/WebSearch'
- $ref: '#/components/parameters/SystemPrompt'
- $ref: '#/components/parameters/MaxTokens'
- $ref: '#/components/parameters/ReasoningEffort'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
responses:
'200':
$ref: '#/components/responses/TextSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
post:
operationId: postText
summary: Generate text from a prompt or messages JSON body
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
requestBody:
$ref: '#/components/requestBodies/TextRequest'
responses:
'200':
$ref: '#/components/responses/TextSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
/v2:
post:
operationId: postV2Messages
summary: Generate text from canonical messages
description: >-
The current messages-only operation. `messages` is required. User
messages may include ordered inline or tenant-asset-backed image and
audio attachments. `model`, `web_search`, `max_tokens`, and
`reasoning_effort` are optional. Omitting `reasoning_effort` selects
the tenant or route default. A supplied value must be non-blank and
supported by the resolved route. The selected provider offering owns
media admission and transport limits. Unsupported media or route
capabilities return HTTP 400 before an upstream call. The service
rejects an encoded request body above 8 MiB before JSON decoding. A
smaller catalog-derived body limit applies when configured. Current
Moonshot Kimi image routes preserve attachment order and exact bytes
through Chat Completions Data URL blocks.
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/ResponseFormat'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/RequestTimeout'
requestBody:
$ref: '#/components/requestBodies/V2Request'
responses:
'200':
$ref: '#/components/responses/TextSuccess'
'400':
$ref: '#/components/responses/V2BadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/AssetFailure'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
'500':
$ref: '#/components/responses/AssetFailure'
/model/v1/assets:
post:
operationId: uploadTenantAsset
summary: Upload exact tenant media bytes
description: >-
Stores one hash-bound image or audio asset for the configured retention
period. The authenticated tenant owns the returned opaque asset id.
tags:
- Proxy
security:
- TenantClientKey: []
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/AssetSHA256'
- $ref: '#/components/parameters/RequestTimeout'
requestBody:
$ref: '#/components/requestBodies/AssetUpload'
responses:
'201':
$ref: '#/components/responses/AssetCreated'
'400':
$ref: '#/components/responses/AssetFailure'
'403':
$ref: '#/components/responses/ProxyForbidden'
'413':
$ref: '#/components/responses/AssetFailure'
'499':
$ref: '#/components/responses/CallerClosed'
'504':
$ref: '#/components/responses/ProxyTimeout'
'500':
$ref: '#/components/responses/AssetFailure'
/model/v1/assets/{asset_id}:
delete:
operationId: deleteTenantAsset
summary: Delete one tenant asset
tags:
- Proxy
security:
- TenantClientKey: []
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/AssetID'
responses:
'204':
description: The asset is deleted.
'403':
$ref: '#/components/responses/ProxyForbidden'
'404':
$ref: '#/components/responses/AssetFailure'
'410':
$ref: '#/components/responses/AssetFailure'
'500':
$ref: '#/components/responses/AssetFailure'
/dictate:
post:
operationId: postDictation
summary: Transcribe an audio upload
tags:
- Proxy
security:
- TenantClientKey: []
x-llm-proxy-allow-undeclared-query: true
parameters:
- $ref: '#/components/parameters/TenantClientKey'
- $ref: '#/components/parameters/Provider'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/RequestTimeout'
requestBody:
$ref: '#/components/requestBodies/DictationRequest'
responses:
'200':
$ref: '#/components/responses/DictationSuccess'
'400':
$ref: '#/components/responses/ProxyBadRequest'
'403':
$ref: '#/components/responses/ProxyForbidden'
'413':
$ref: '#/components/responses/ProxyPayloadTooLarge'
'429':
$ref: '#/components/responses/ProxyRateLimited'
'499':
$ref: '#/components/responses/CallerClosed'
'502':
$ref: '#/components/responses/ProxyBadGateway'
'503':
$ref: '#/components/responses/ProxyUnavailable'
'504':
$ref: '#/components/responses/ProxyTimeout'
/config-ui.yaml:
get:
operationId: getBrowserConfiguration
summary: Read the browser runtime configuration
tags:
- Configuration
security: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
description: Current browser runtime configuration.
headers:
Cache-Control:
description: Prevents persistence of environment-specific browser configuration.
schema:
type: string
const: no-store
x-required: true
content:
application/yaml:
schema:
type: string
/api/public/capabilities:
get:
operationId: getPublicCapabilities
summary: Read the public normalized model capability catalog
description: Returns the deterministic, secret-free projection of model publishers, families, exact models, provider offerings, and public proxy request limits.
tags:
- Capabilities
security: []
responses:
'200':
description: Current public capability catalog.
headers:
Cache-Control:
description: Allows short-lived caching of the public catalog.
schema:
type: string
const: public, max-age=300
x-required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCapabilityCatalog'
/api/management/account:
get:
operationId: getManagementAccount
summary: Read the authenticated user and owned tenant summaries
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AccountSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/usage:
get:
operationId: getManagementAccountUsage
summary: Read interval-scoped usage across every owned tenant
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/usage/failures:
get:
operationId: getManagementAccountUsageFailures
summary: Read safe failure details across every owned tenant and interval
description: Returns a newest-first snapshot page of failed managed proxy events across every tenant owned by the authenticated user. Each row identifies its tenant by opaque ID and current name while exposing only bounded diagnostic metadata and canonical outcome codes. Rows never include prompts, responses, provider bodies, free-form errors, credentials, or another user's ownership data.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageFailureLimit'
- $ref: '#/components/parameters/UsageFailureCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AccountUsageFailuresSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants:
post:
operationId: createManagementTenant
summary: Create an owned tenant
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/TenantNameRequest'
responses:
'201':
$ref: '#/components/responses/TenantProfileCreated'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/admin/users:
get:
operationId: getManagementAdminUsers
summary: Read the administrative user and tenant usage summary
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/AdminUsersSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}:
get:
operationId: getManagementTenant
summary: Read an owned tenant profile
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
put:
operationId: renameManagementTenant
summary: Rename an owned tenant
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/TenantNameRequest'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
delete:
operationId: deleteManagementTenant
summary: Delete an owned non-final tenant
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'204':
description: Tenant deleted.
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/usage:
get:
operationId: getManagementTenantUsage
summary: Read interval-scoped usage for an owned tenant
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/usage/failures:
get:
operationId: getManagementTenantUsageFailures
summary: Read safe failure details for an owned tenant and interval
description: Returns a newest-first snapshot page of failed managed proxy events. Rows expose only bounded diagnostic metadata and canonical outcome codes; they never include prompts, responses, provider bodies, free-form errors, credentials, or ownership identifiers. Historical rows use status-derived normalized outcome codes rather than reconstructed error messages.
tags:
- Management
security:
- TAuthSession: []
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/UsageInterval'
- $ref: '#/components/parameters/UsageFailureLimit'
- $ref: '#/components/parameters/UsageFailureCursor'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/UsageFailuresSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'404':
$ref: '#/components/responses/ManagementNotFound'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/provider-keys/{provider}:
put:
operationId: putManagementProviderKey
summary: Verify and save provider settings and a provider credential
description: A nonempty api_key performs exactly one provider-authenticated verification operation for the selected provider, text model, and provider base URL under the management request context and shared upstream admission/rate-limit boundary. Changing a saved DashScope base_url also verifies the retained key against the new URL. Only a successful verification atomically persists the credential and submitted settings, reconciles routing defaults, and returns a keyed profile. Rejection and unconfirmed transient outcomes never mutate the provider key, settings, defaults, or managed usage. An empty api_key retains the existing verified credential. The operation returns 409 without a mutation if that retained credential changes before the verified update can persist.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/ProviderKeyRequest'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'409':
$ref: '#/components/responses/ManagementConflict'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'422':
$ref: '#/components/responses/ProviderKeyRejected'
'429':
$ref: '#/components/responses/ProviderKeyVerificationRateLimited'
'500':
$ref: '#/components/responses/ManagementInternalError'
'503':
$ref: '#/components/responses/ProviderKeyVerificationUnavailable'
'504':
$ref: '#/components/responses/ProviderKeyVerificationTimedOut'
delete:
operationId: deleteManagementProviderKey
summary: Remove provider settings and a provider credential
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- $ref: '#/components/parameters/OptionalOrigin'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/provider-keys/{provider}/reveal:
post:
operationId: revealManagementProviderKey
summary: Reveal one saved provider credential
description: This credentialed action requires the exact configured public Origin in addition to the TAuth session.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/ProviderPath'
- $ref: '#/components/parameters/RequiredOrigin'
requestBody:
$ref: '#/components/requestBodies/EmptyJSONRequest'
responses:
'200':
$ref: '#/components/responses/ProviderKeyRevealSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/defaults:
put:
operationId: putManagementTenantDefaults
summary: Replace the tenant routing defaults
description: Every nonempty provider/model pair must use a provider for which this tenant has a saved API key. The text pair is empty only when no provider key exists. The dictation pair is empty when no keyed provider supports dictation.
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/DefaultsRequest'
responses:
'200':
$ref: '#/components/responses/TenantProfileSuccess'
'400':
$ref: '#/components/responses/ManagementBadRequest'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
/api/management/tenants/{tenant_id}/secrets:
post:
operationId: postManagementTenantSecret
summary: Generate and replace the tenant client secret
tags:
- Management
security:
- TAuthSession: []
x-llm-proxy-required-request-content-type: application/json
parameters:
- $ref: '#/components/parameters/TenantID'
- $ref: '#/components/parameters/OptionalOrigin'
requestBody:
$ref: '#/components/requestBodies/EmptyJSONRequest'
responses:
'200':
$ref: '#/components/responses/TenantSecretSuccess'
'401':
$ref: '#/components/responses/ManagementUnauthorized'
'403':
$ref: '#/components/responses/ManagementForbidden'
'404':
$ref: '#/components/responses/ManagementNotFound'
'415':
$ref: '#/components/responses/ManagementUnsupportedMediaType'
'500':
$ref: '#/components/responses/ManagementInternalError'
components:
securitySchemes:
TenantClientKey:
type: apiKey
in: query
name: key
description: The tenant client secret generated by the management API.
TAuthSession:
type: apiKey
in: cookie
name: app_session_llm_proxy
description: The exact deployment-configured TAuth session cookie. The production cookie name is configured through management.session_cookie_name.
parameters:
TenantClientKey:
name: key
in: query
required: true
description: Tenant client secret.
schema:
type: string
minLength: 1
Prompt:
name: prompt
in: query
required: true
description: User prompt.
schema:
type: string
minLength: 1
Provider:
name: provider
in: query
required: false
description: Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default.
schema:
type: string
minLength: 1
Model:
name: model
in: query
required: false
description: Model identifier. Omission uses the resolved provider default.
schema:
type: string
minLength: 1
WebSearch:
name: web_search
in: query
required: false
description: Exact boolean query parameter. Use true or false; omission disables web search. Any other supplied spelling is invalid and returns HTTP 400.
schema:
type: boolean
SystemPrompt:
name: system_prompt
in: query
required: false
schema:
type: string
MaxTokens:
name: max_tokens
in: query
required: false
description: Initial per-attempt output budget. The same budget is reused when the proxy requests a missing suffix; after a zero-text output-budget stop, a configured model output limit bounds any generic increase.
schema:
type: integer
minimum: 1
ReasoningEffort:
name: reasoning_effort
in: query
required: false
description: Non-blank effort supported by the resolved route. Omission selects the tenant or route default.
schema:
type: string
minLength: 1
ResponseFormat:
name: format
in: query
required: false
description: Preferred response media type. Unknown values select text/plain.
schema:
type: string
enum:
- text/plain
- application/json
- application/xml
- text/xml
- text/csv
Accept:
name: Accept
in: header
required: false
description: Response media preference used when format is omitted.
schema:
type: string
RequestTimeout:
name: X-LLM-Proxy-Request-Timeout-Seconds
in: header
required: false
description: A positive whole-second request budget no greater than the server maximum. Omission selects the configured default.
schema:
type: integer
minimum: 1
AssetSHA256:
name: X-LLM-Proxy-Asset-SHA256
in: header
required: true
description: Lowercase hexadecimal SHA-256 of the exact request body.
schema:
type: string
pattern: ^[0-9a-f]{64}$
AssetID:
name: asset_id
in: path
required: true
description: Opaque tenant asset identifier.
schema:
type: string
pattern: ^ast_[0-9a-f]{32}$
TenantID:
name: tenant_id
in: path
required: true
description: Opaque tenant identifier from the authenticated account response.
schema:
type: string
minLength: 1
ProviderPath:
name: provider
in: path
required: true
description: Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid.
schema:
type: string
minLength: 1
UsageInterval:
name: interval
in: query
required: true
schema:
type: string
enum:
- 1d
- 7d
- 30d
- all
UsageFailureLimit:
name: limit
in: query
required: false
description: Maximum failure rows in this page. Omission selects 25.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
UsageFailureCursor:
name: cursor
in: query
required: false
description: Opaque continuation cursor returned by the preceding page for the same interval and reporting scope.
schema:
type: string
minLength: 1
OptionalOrigin:
name: Origin
in: header
required: false
description: When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers.
schema:
type: string
format: uri
RequiredOrigin:
name: Origin
in: header
required: true
description: Must exactly match the configured public origin.
schema:
type: string
format: uri
requestBodies:
TextRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TextRequest'
V2Request:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2Request'
DictationRequest:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/DictationRequest'
encoding:
audio:
contentType: audio/*,application/octet-stream
AssetUpload:
required: true
content:
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
audio/m4a:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
audio/wav:
schema:
type: string
format: binary
TenantNameRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TenantNameRequest'
ProviderKeyRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderKeyRequest'
DefaultsRequest:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultsRequest'
EmptyJSONRequest:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
responses:
TextSuccess:
description: 'Complete generated text in the selected representation. The selected model has one validated wire contract and one execution lifecycle; no lifecycle is inferred from an endpoint or upstream id. The proxy internally observes queued and in_progress states for OpenAI Responses and background-capable Gemini Interactions while keeping every public operation blocking; synchronous Gemini Interactions must return an immediate terminal state. Separately, it continues exact output-budget stops through new provider calls: OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, Gemini Interactions incomplete, and Anthropic max_tokens. HTTP 200 is returned only after the adapter reports its complete signal: OpenAI or Gemini completed, Chat stop, or Anthropic end_turn|stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states never return text as success.'
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Response-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
X-LLM-Proxy-Total-Tokens:
$ref: '#/components/headers/OptionalTokenCount'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/TextJSONResponse'
application/xml:
schema:
type: string
text/csv:
schema:
type: string
DictationSuccess:
description: Transcription result.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/DictationResponse'
ProxyBadRequest:
description: The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/ProxyErrorEnvelope'
ProxyForbidden:
description: The tenant client key is absent or unknown.
content:
text/plain:
schema:
type: string
const: unknown client key
ProxyPayloadTooLarge:
description: The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
V2BadRequest:
description: The canonical message input or referenced asset is invalid.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ProxyErrorEnvelope'
- $ref: '#/components/schemas/AssetErrorEnvelope'
AssetCreated:
description: The asset is available to its authenticated tenant.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantAsset'
AssetFailure:
description: The asset operation failed with a stable safe code.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/OptionalResolvedRequestTimeout'
content:
application/json:
schema:
$ref: '#/components/schemas/AssetErrorEnvelope'
ProxyRateLimited:
description: The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
CallerClosed:
description: The caller canceled or closed the request.
ProxyBadGateway:
description: The selected upstream provider failed, returned a non-429 unsuccessful HTTP status, or returned an unusable success payload. Output-budget stops are continued internally and do not create this response. The response contains only sanitized provider metadata and never exposes partial generated text, token-count headers, a raw provider body, or a provider error message; provider-reported usage can still be retained in managed failure accounting.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
X-LLM-Proxy-Request-ID:
$ref: '#/components/headers/ProxyRequestID'
Retry-After:
$ref: '#/components/headers/SafeRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorEnvelope'
ProxyUnavailable:
description: The selected provider is not configured or the bounded request queue is full.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
ProxyTimeout:
description: The proxy request budget or upstream operation timed out.
headers:
X-LLM-Proxy-Request-Timeout-Seconds:
$ref: '#/components/headers/ResolvedRequestTimeout'
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/ProxyErrorEnvelope'
AccountSuccess:
description: Authenticated account snapshot.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ManagementAccount'
TenantProfileSuccess:
description: Current tenant profile.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
TenantProfileCreated:
description: Created tenant profile.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantProfile'
UsageSuccess:
description: Usage summary for the exact requested interval and authenticated reporting scope.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageSummary'
UsageFailuresSuccess:
description: Snapshot page of safe tenant failure details for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageFailurePage'
AccountUsageFailuresSuccess:
description: Snapshot page of safe failure details across every owned tenant for the exact requested interval.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUsageFailurePage'
AdminUsersSuccess:
description: Administrative user and tenant usage summary.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUsersSummary'
ProviderKeyRevealSuccess:
description: The saved provider credential. Never persist or log this response.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderKeyReveal'
TenantSecretSuccess:
description: The newly generated tenant client secret and current profile. The secret is returned only by this response.
headers:
Cache-Control:
$ref: '#/components/headers/NoStore'
content:
application/json:
schema:
$ref: '#/components/schemas/TenantSecret'
ManagementBadRequest:
description: Malformed or invalid management input.
content:
text/plain:
schema:
type: string
ManagementUnauthorized:
description: The TAuth session is absent or invalid.
ManagementForbidden:
description: The user lacks the required role or the supplied Origin is not allowed.
ManagementNotFound:
description: The tenant or provider credential does not exist within the authenticated ownership boundary.
ManagementConflict:
description: The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began.
content:
text/plain:
schema:
type: string
ManagementUnsupportedMediaType:
description: A management mutation did not supply application/json.
ProviderKeyRejected:
description: The candidate credential was rejected or cannot access the selected text model. Nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_rejected
ProviderKeyVerificationRateLimited:
description: The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_rate_limited
ProviderKeyVerificationUnavailable:
description: The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_unavailable
ProviderKeyVerificationTimedOut:
description: The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved.
content:
text/plain:
schema:
type: string
const: provider_key_verification_timed_out
ManagementInternalError:
description: The management operation failed internally.
content:
text/plain:
schema:
type: string
headers:
ResolvedRequestTimeout:
description: The resolved whole-second budget used for the request.
schema:
type: integer
minimum: 1
x-required: true
OptionalResolvedRequestTimeout:
description: Present after the supplied timeout header passes validation.
schema:
type: integer
minimum: 1
ProxyRequestID:
description: Proxy-owned identifier matching error.request_id and the request_id field in structured proxy logs.
schema:
type: string
minLength: 1
x-required: true
SafeRetryAfter:
description: Present only when the provider supplied a syntactically valid Retry-After value. Delta seconds are normalized to unsigned decimal form and HTTP dates are normalized to IMF-fixdate.
schema:
type: string
minLength: 1
OptionalTokenCount:
description: Provider-reported token count when available.
schema:
type: integer
minimum: 0
NoStore:
description: Prevents persistence of authenticated or secret-bearing management responses.
schema:
type: string
const: no-store
x-required: true
schemas:
PublicCapabilityCatalog:
type: object
additionalProperties: false
required:
- revision
- operations
- providers
- publishers
- families
- models
- offerings
- prices
- counts
- max_prompt_bytes
- max_input_audio_bytes
- max_request_timeout_seconds
properties:
revision:
type: string
minLength: 1
operations:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelOperation'
providers:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicProviderCapability'
publishers:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelPublisher'
families:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicModelFamily'
models:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicExactModelCapability'
offerings:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicProviderOffering'
prices:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PublicPriceDescriptor'
counts:
$ref: '#/components/schemas/PublicCapabilityCounts'
max_prompt_bytes:
type: integer
format: int64
minimum: 1
max_input_audio_bytes:
type: integer
format: int64
minimum: 1
max_request_timeout_seconds:
type: integer
minimum: 1
PublicProviderCapability:
type: object
additionalProperties: false
required:
- identifier
- label
- credential_kinds
properties:
identifier:
type: string
minLength: 1
label:
type: string
minLength: 1
credential_kinds:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- api_key
PublicModelOperation:
type: object
additionalProperties: false
required:
- id
- input_artifacts
- output_artifacts
properties:
id:
type: string
enum:
- text
- dictation
- video_generation
input_artifacts:
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/PublicArtifactKind'
output_artifacts:
type: array
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/PublicArtifactKind'
PublicArtifactKind:
type: string
enum:
- text
- image
- audio
- video
PublicModelPublisher:
type: object
additionalProperties: false
required:
- identifier
- label
- model_count
properties:
identifier:
type: string
minLength: 1
label:
type: string
minLength: 1
model_count:
type: integer
minimum: 1
PublicModelFamily:
type: object
additionalProperties: false
required:
- identifier
- publisher
- label
- weight_access
properties:
identifier:
type: string
minLength: 1
publisher:
type: string
minLength: 1
label:
type: string
minLength: 1
weight_access:
type: string
enum:
- proprietary
- open_weights
PublicExactModelCapability:
type: object
additionalProperties: false
required:
- identifier
- publisher
- family
- version
- operations
- media_inputs
- capabilities
- provider_offerings
properties:
identifier:
type: string
minLength: 1
publisher:
type: string
minLength: 1
family:
type: string
minLength: 1
version:
type: string
minLength: 1
operations:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- video_generation
media_inputs:
type: array
uniqueItems: true
items:
type: string
enum:
- image
- audio
capabilities:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- web_search
- image_input
- audio_input
- reasoning
- video_generation
provider_offerings:
type: array
minItems: 1
uniqueItems: true
items:
type: string
minLength: 1
PublicProviderOffering:
type: object
additionalProperties: false
required:
- identifier
- provider
- model
- capabilities
- wire_contract
- execution_lifecycle
- output_token_limit
- reasoning_efforts
- controls
- limits
- media_limits
properties:
identifier:
type: string
minLength: 1
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
capabilities:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- text
- dictation
- web_search
- image_input
- audio_input
- reasoning
- video_generation
wire_contract:
type: string
minLength: 1
execution_lifecycle:
type: string
enum:
- synchronous_completion
- pollable_resource
output_token_limit:
type: integer
minimum: 0
reasoning_efforts:
type: array
uniqueItems: true
items:
type: string
minLength: 1
controls:
type: array
items:
$ref: '#/components/schemas/PublicCatalogControl'
limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogLimit'
media_limits:
type: array
items:
$ref: '#/components/schemas/PublicCatalogMediaLimit'
PublicCatalogControl:
type: object
additionalProperties: false
required:
- id
- kind
- values
- minimum
- maximum
- account_dependent
properties:
id:
type: string
minLength: 1
kind:
type: string
enum:
- enum
- integer
- boolean
values:
type: array
uniqueItems: true
items:
type: string
minLength: 1
minimum:
oneOf:
- type: integer
minimum: 0
- type: 'null'
maximum:
oneOf:
- type: integer
minimum: 0
- type: 'null'
account_dependent:
type: boolean
PublicCatalogLimit:
type: object
additionalProperties: false
required:
- id
- value
- unit
- account_dependent
properties:
id:
type: string
minLength: 1
value:
oneOf:
- type: integer
minimum: 0
- type: 'null'
unit:
type: string
minLength: 1
account_dependent:
type: boolean
PublicCatalogMediaLimit:
type: object
additionalProperties: false
required:
- id
- media_type
- transport
- status
- value
- unit
- scope
- source
- last_verified
properties:
id:
type: string
minLength: 1
media_type:
type: string
enum:
- all
- image
- audio
transport:
type: string
enum:
- any
- inline
- file
status:
type: string
enum:
- bounded
- unbounded
- unknown
value:
oneOf:
- type: integer
minimum: 1
- type: 'null'
unit:
type: string
enum:
- bytes
- files
scope:
type: string
enum:
- attachment
- attachment_encoded_bytes
- request
- request_encoded_bytes
source:
type: string
format: uri
pattern: '^https://'
last_verified:
type: string
format: date
PublicPriceDescriptor:
type: object
additionalProperties: false
required:
- provider
- model
- operation
- available
- rates
- minimum_charge
- source
- last_verified
- unavailable_reason
properties:
provider:
type: string
minLength: 1
model:
type: string
minLength: 1
operation:
type: string
enum:
- text
- dictation
- video_generation
available:
type: boolean
rates:
type: array
items:
$ref: '#/components/schemas/PublicPriceRate'
minimum_charge:
oneOf:
- $ref: '#/components/schemas/PublicMinimumCharge'
- type: 'null'
source:
type: string
format: uri
pattern: '^https://'
last_verified:
type: string
format: date
unavailable_reason:
type: string
PublicPriceRate:
type: object
additionalProperties: false
required:
- component
- currency
- rate
- unit
- conditions
properties:
component:
type: string
minLength: 1
currency:
type: string
const: USD
rate:
type: number
minimum: 0
unit:
type: string
minLength: 1
conditions:
$ref: '#/components/schemas/PublicPriceConditions'
PublicMinimumCharge:
type: object
additionalProperties: false
required:
- currency
- amount
- unit
properties:
currency:
type: string
const: USD
amount:
type: number
minimum: 0
unit:
type: string
minLength: 1
PublicPriceConditions:
type: object
additionalProperties: false
required:
- resolution
- generated_audio
- input_media
- output_media
- duration
- quantity
- quality
- mode
- api_version
- avatar_type
- billing_mode
- billing_outcome
properties:
resolution: {type: string}
generated_audio: {type: string}
input_media: {type: string}
output_media: {type: string}
duration: {type: string}
quantity: {type: string}
quality: {type: string}
mode: {type: string}
api_version: {type: string}
avatar_type: {type: string}
billing_mode: {type: string}
billing_outcome: {type: string}
PublicCapabilityCounts:
type: object
additionalProperties: false
required:
- providers
- model_publishers
- model_families
- exact_models
- provider_offerings
properties:
providers:
type: integer
minimum: 1
model_publishers:
type: integer
minimum: 1
model_families:
type: integer
minimum: 1
exact_models:
type: integer
minimum: 1
provider_offerings:
type: integer
minimum: 1
ChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
enum:
- system
- user
- assistant
content:
type: string
minLength: 1
order:
type: integer
minimum: 0
MessageAttachment:
description: One provider-neutral image or audio input with a MIME type that matches its declared media type. The resolved catalog route determines support. Current Moonshot Kimi image routes accept the image variants.
oneOf:
- $ref: '#/components/schemas/ImageMessageAttachment'
- $ref: '#/components/schemas/AudioMessageAttachment'
- $ref: '#/components/schemas/ImageAssetMessageAttachment'
- $ref: '#/components/schemas/AudioAssetMessageAttachment'
ImageMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- data
- sha256
properties:
type:
type: string
const: image
mime_type:
type: string
enum:
- image/jpeg
- image/png
- image/webp
data:
type: string
minLength: 4
description: Exact nonempty media bytes encoded as canonical padded RFC 4648 base64.
sha256:
type: string
pattern: ^[0-9a-f]{64}$
description: Lowercase hexadecimal SHA-256 of the decoded media bytes.
AudioMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- data
- sha256
properties:
type:
type: string
const: audio
mime_type:
type: string
enum:
- audio/m4a
- audio/mpeg
- audio/wav
data:
type: string
minLength: 4
description: Exact nonempty media bytes encoded as canonical padded RFC 4648 base64.
sha256:
type: string
pattern: ^[0-9a-f]{64}$
description: Lowercase hexadecimal SHA-256 of the decoded media bytes.
ImageAssetMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- asset_id
- sha256
properties:
type:
type: string
const: image
mime_type:
type: string
enum:
- image/jpeg
- image/png
- image/webp
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
sha256:
type: string
pattern: ^[0-9a-f]{64}$
AudioAssetMessageAttachment:
type: object
additionalProperties: false
required:
- type
- mime_type
- asset_id
- sha256
properties:
type:
type: string
const: audio
mime_type:
type: string
enum:
- audio/m4a
- audio/mpeg
- audio/wav
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
sha256:
type: string
pattern: ^[0-9a-f]{64}$
TenantAsset:
type: object
additionalProperties: false
required:
- asset_id
- mime_type
- size_bytes
- sha256
- state
- created_at
- expires_at
properties:
asset_id:
type: string
pattern: ^ast_[0-9a-f]{32}$
mime_type:
type: string
enum:
- image/jpeg
- image/png
- image/webp
- audio/m4a
- audio/mpeg
- audio/wav
size_bytes:
type: integer
format: int64
minimum: 1
sha256:
type: string
pattern: ^[0-9a-f]{64}$
state:
type: string
const: available
created_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
AssetErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
enum:
- asset_invalid
- asset_not_found
- asset_expired
- asset_deleted
- asset_mime_mismatch
- asset_digest_mismatch
- asset_too_large
- asset_store_error
V2ChatMessage:
description: A user message that may carry attachments, or a text-only system or assistant message.
oneOf:
- $ref: '#/components/schemas/V2UserChatMessage'
- $ref: '#/components/schemas/V2SystemOrAssistantChatMessage'
V2UserChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
const: user
content:
type: string
minLength: 1
attachments:
type: array
minItems: 1
description: Ordered exact media inputs accepted only when the resolved model declares each media type.
items:
$ref: '#/components/schemas/MessageAttachment'
order:
type: integer
minimum: 0
V2SystemOrAssistantChatMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
enum:
- system
- assistant
content:
type: string
minLength: 1
order:
type: integer
minimum: 0
TextRequest:
type: object
additionalProperties: false
properties:
prompt:
type: string
minLength: 1
messages:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ChatMessage'
model:
type: string
minLength: 1
web_search:
type: boolean
system_prompt:
type: string
max_tokens:
type: integer
minimum: 1
description: Initial per-attempt output budget. Reused for missing-suffix attempts, with any zero-progress increase bounded by the configured model output limit.
reasoning_effort:
type: string
minLength: 1
V2Request:
type: object
additionalProperties: false
required:
- messages
properties:
messages:
type: array
minItems: 1
description: All messages must have an allowed role and non-blank content, include at least one user message, and either all omit order or all provide unique non-negative order values. Only user messages may carry attachments; message order and attachment order are preserved.
items:
$ref: '#/components/schemas/V2ChatMessage'
model:
type: string
minLength: 1
description: Omission selects the resolved provider default.
web_search:
type: boolean
description: The resolved route must declare web-search capability when true.
max_tokens:
type: integer
minimum: 1
description: Initial per-attempt output budget. Reused for missing-suffix attempts, with any zero-progress increase bounded by the configured model output limit.
reasoning_effort:
type: string
minLength: 1
description: Omission selects the tenant or route default. An explicit value must be non-blank and supported by the resolved provider/model route. Kimi K3 accepts low, high, or max.
DictationRequest:
type: object
additionalProperties: false
required:
- audio
properties:
audio:
type: string
format: binary
description: The canonical incoming audio file part.
DictationResponse:
type: object
additionalProperties: false
required:
- text
properties:
text:
type: string
TokenUsage:
type: object
additionalProperties: false
required:
- request_tokens
- response_tokens
- total_tokens
properties:
request_tokens:
type: integer
minimum: 0
response_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
TextJSONResponse:
type: object
additionalProperties: false
required:
- request
- response
- object
- model
- choices
- messages
properties:
request:
type: string
response:
type: string
object:
type: string
const: chat.completion
model:
type: string
choices:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Choice'
messages:
type: array
items:
$ref: '#/components/schemas/ResponseMessage'
usage:
$ref: '#/components/schemas/TokenUsage'
Choice:
type: object
additionalProperties: false
required:
- index
- finish_reason
- message
properties:
index:
type: integer
minimum: 0
finish_reason:
type: string
const: stop
message:
$ref: '#/components/schemas/ResponseMessage'
ResponseMessage:
type: object
additionalProperties: false
required:
- role
- content
properties:
role:
type: string
enum:
- system
- user
- assistant
content:
type: string
order:
type: integer
minimum: 0
ProxyErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
enum:
- invalid_request_timeout
- request_timeout
max_request_timeout_seconds:
type: integer
minimum: 1
request_timeout_seconds:
type: integer
minimum: 1
ProviderErrorEnvelope:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
additionalProperties: false
required:
- code
- provider
- upstream_status
- retryable
- request_id
- retry_after
properties:
code:
type: string
enum:
- provider_error
- provider_media_limit_exceeded
- provider_rate_limited
provider:
type: string
minLength: 1
description: Canonical provider selector resolved for the request.
upstream_status:
oneOf:
- type: integer
minimum: 100
maximum: 599
- type: 'null'
description: Exact provider HTTP status when an upstream response was received; null for transport, request-construction, and response-protocol failures without a usable unsuccessful HTTP response.
retryable:
type: boolean
description: True only for upstream HTTP 408, 425, 429, 500, 502, 503, or 504. This classifies the provider condition; clients remain responsible for duplicate-work and billing consequences before retrying.
request_id:
type: string
minLength: 1
description: Proxy-owned correlation identifier also returned in X-LLM-Proxy-Request-ID and recorded in structured proxy logs.
retry_after:
oneOf:
- type: string
minLength: 1
- type: 'null'
description: Validated and normalized provider Retry-After value, or null when the provider omitted it or supplied an invalid value. A non-null value is also returned in the Retry-After response header.
TenantNameRequest:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
ProviderKeyRequest:
type: object
additionalProperties: false
required:
- api_key
- base_url
- text_model
- system_prompt
properties:
api_key:
type: string
description: An unverified new or replacement provider key. A nonempty value is verified against the exact path provider, selected text_model, and submitted base_url before any persistence. Send an empty string to retain the tenant's existing verified credential; an empty value is rejected when no credential exists.
base_url:
type: string
description: Exact tenant-owned Singapore Model Studio URL for dashscope. It must use https://{resource-id}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. It must be empty for every other provider.
text_model:
type: string
minLength: 1
system_prompt:
type: string
DefaultsRequest:
type: object
additionalProperties: false
required:
- provider
- model
- dictation_provider
- dictation_model
- system_prompt
- reasoning_effort
properties:
provider:
type: string
description: Canonical keyed text-provider id, or empty together with model when the tenant has no saved provider key.
model:
type: string
description: Canonical model for provider, or empty together with provider when the tenant has no saved provider key.
dictation_provider:
type: string
description: Canonical keyed dictation-capable provider id, or empty together with dictation_model when no keyed provider supports dictation.
dictation_model:
type: string
description: Canonical model for dictation_provider, or empty together with dictation_provider when no keyed provider supports dictation.
system_prompt:
type: string
reasoning_effort:
type: string
EmptyObject:
type: object
additionalProperties: false
properties: {}
ManagementAccount:
type: object
additionalProperties: false
required:
- user
- tenants
properties:
user:
$ref: '#/components/schemas/ManagementUser'
tenants:
type: array
items:
$ref: '#/components/schemas/TenantSummary'
ManagementUser:
type: object
additionalProperties: false
required:
- id
- is_admin
properties:
id:
type: string
minLength: 1
email:
type: string
display_name:
type: string
avatar_url:
type: string
is_admin:
type: boolean
TenantSummary:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- created_at
- updated_at
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
TenantProfile:
type: object
additionalProperties: false
required:
- tenant
- providers
- proxy
properties:
tenant:
$ref: '#/components/schemas/Tenant'
providers:
type: array
items:
$ref: '#/components/schemas/ProviderProfile'
proxy:
$ref: '#/components/schemas/ProxyPaths'
Tenant:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- defaults
- created_at
- updated_at
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
defaults:
$ref: '#/components/schemas/TenantDefaults'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
TenantDefaults:
type: object
additionalProperties: false
required:
- provider
- model
- dictation_provider
- dictation_model
- system_prompt
- reasoning_effort
properties:
provider:
type: string
description: Canonical keyed text-provider id, or empty when the tenant has no saved provider key.
model:
type: string
description: Canonical text model paired with provider, or empty when provider is empty.
dictation_provider:
type: string
description: Canonical keyed dictation-capable provider id, or empty when no keyed provider supports dictation.
dictation_model:
type: string
description: Canonical dictation model paired with dictation_provider, or empty when dictation_provider is empty.
system_prompt:
type: string
reasoning_effort:
type: string
ProviderProfile:
type: object
additionalProperties: false
required:
- id
- label
- aliases
- has_key
- base_url
- text_model
- system_prompt
- text_default_model
- text_models
- supports_dictation
- dictation_models
properties:
id:
type: string
label:
type: string
aliases:
type: array
items:
type: string
has_key:
type: boolean
masked_key:
type: string
base_url:
type: string
description: Saved tenant-owned DashScope API URL, or empty for an unconfigured DashScope provider and every other provider.
text_model:
type: string
system_prompt:
type: string
text_default_model:
type: string
text_models:
type: array
items:
$ref: '#/components/schemas/TextModel'
supports_dictation:
type: boolean
dictation_default_model:
type: string
dictation_models:
type: array
items:
type: string
TextModel:
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
reasoning_effort:
$ref: '#/components/schemas/ReasoningEffortCapability'
ReasoningEffortCapability:
type: object
additionalProperties: false
required:
- adapter
- efforts
properties:
adapter:
type: string
efforts:
type: array
items:
type: string
ProxyPaths:
type: object
additionalProperties: false
required:
- text_path
- v2_path
- dictation_path
properties:
text_path:
type: string
const: /
v2_path:
type: string
const: /v2
dictation_path:
type: string
const: /dictate
TenantSecret:
type: object
additionalProperties: false
required:
- secret
- profile
properties:
secret:
type: string
minLength: 1
profile:
$ref: '#/components/schemas/TenantProfile'
ProviderKeyReveal:
type: object
additionalProperties: false
required:
- api_key
properties:
api_key:
type: string
minLength: 1
UsageAggregate:
type: object
additionalProperties: false
required:
- requests
- successful_requests
- failed_requests
- text_requests
- dictation_requests
- request_tokens
- response_tokens
- total_tokens
- average_latency_ms
properties:
requests:
type: integer
minimum: 0
successful_requests:
type: integer
minimum: 0
failed_requests:
type: integer
minimum: 0
text_requests:
type: integer
minimum: 0
dictation_requests:
type: integer
minimum: 0
request_tokens:
type: integer
minimum: 0
response_tokens:
type: integer
minimum: 0
total_tokens:
type: integer
minimum: 0
average_latency_ms:
type: integer
minimum: 0
UsageBucket:
type: object
additionalProperties: false
required:
- start
- data
properties:
start:
type: string
format: date-time
data:
$ref: '#/components/schemas/UsageAggregate'
UsageProvider:
type: object
additionalProperties: false
required:
- provider
- data
properties:
provider:
type: string
data:
$ref: '#/components/schemas/UsageAggregate'
UsageModel:
type: object
additionalProperties: false
required:
- provider
- model
- data
properties:
provider:
type: string
model:
type: string
data:
$ref: '#/components/schemas/UsageAggregate'
UsageStatus:
type: object
additionalProperties: false
required:
- status_code
- requests
properties:
status_code:
type: integer
minimum: 100
requests:
type: integer
minimum: 0
UsageSummary:
type: object
additionalProperties: false
required:
- interval
- bucket_unit
- totals
- buckets
- providers
- models
- status_codes
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
bucket_unit:
type: string
enum:
- hour
- day
- month
totals:
$ref: '#/components/schemas/UsageAggregate'
buckets:
type: array
items:
$ref: '#/components/schemas/UsageBucket'
providers:
type: array
items:
$ref: '#/components/schemas/UsageProvider'
models:
type: array
items:
$ref: '#/components/schemas/UsageModel'
status_codes:
type: array
items:
$ref: '#/components/schemas/UsageStatus'
UsageOutcomeCode:
type: string
enum:
- success
- invalid_request
- payload_too_large
- rate_limited
- service_unavailable
- request_timeout
- upstream_error
UsageFailure:
type: object
additionalProperties: false
required:
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
model:
type: string
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageOutcomeCode'
latency_ms:
type: integer
minimum: 0
UsageFailurePage:
type: object
additionalProperties: false
required:
- interval
- failures
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
failures:
type: array
items:
$ref: '#/components/schemas/UsageFailure'
next_cursor:
type: string
minLength: 1
AccountUsageFailure:
type: object
additionalProperties: false
required:
- tenant_id
- tenant_name
- occurred_at
- endpoint
- provider
- model
- status_code
- outcome_code
- latency_ms
properties:
tenant_id:
type: string
minLength: 1
tenant_name:
type: string
minLength: 1
occurred_at:
type: string
format: date-time
endpoint:
type: string
provider:
type: string
model:
type: string
status_code:
type: integer
minimum: 100
maximum: 599
outcome_code:
$ref: '#/components/schemas/UsageOutcomeCode'
latency_ms:
type: integer
minimum: 0
AccountUsageFailurePage:
type: object
additionalProperties: false
required:
- interval
- failures
properties:
interval:
type: string
enum:
- 1d
- 7d
- 30d
- all
failures:
type: array
items:
$ref: '#/components/schemas/AccountUsageFailure'
next_cursor:
type: string
minLength: 1
AdminUsageSummary:
type: object
additionalProperties: false
required:
- period_days
- totals
- daily
- providers
- models
- status_codes
properties:
period_days:
type: integer
minimum: 1
totals:
$ref: '#/components/schemas/UsageAggregate'
daily:
type: array
items:
type: object
additionalProperties: false
required:
- date
- data
properties:
date:
type: string
format: date
data:
$ref: '#/components/schemas/UsageAggregate'
providers:
type: array
items:
$ref: '#/components/schemas/UsageProvider'
models:
type: array
items:
$ref: '#/components/schemas/UsageModel'
status_codes:
type: array
items:
$ref: '#/components/schemas/UsageStatus'
AdminTenant:
type: object
additionalProperties: false
required:
- id
- name
- has_secret
- created_at
- updated_at
- usage
properties:
id:
type: string
name:
type: string
has_secret:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
usage:
$ref: '#/components/schemas/AdminUsageSummary'
AdminUser:
type: object
additionalProperties: false
required:
- user
- tenant_count
- tenants
properties:
user:
$ref: '#/components/schemas/ManagementUser'
tenant_count:
type: integer
minimum: 0
tenants:
type: array
items:
$ref: '#/components/schemas/AdminTenant'
AdminUsersSummary:
type: object
additionalProperties: false
required:
- period_days
- users
properties:
period_days:
type: integer
minimum: 1
users:
type: array
items:
$ref: '#/components/schemas/AdminUser'
Operations
GET
/Generate text from a query prompt
POST/Generate text from a prompt or messages JSON body
GET/api/management/accountRead the authenticated user and owned tenant summaries
GET/api/management/admin/usersRead the administrative user and tenant usage summary
POST/api/management/tenantsCreate an owned tenant
DELETE/api/management/tenants/{tenant_id}Delete an owned non-final tenant
GET/api/management/tenants/{tenant_id}Read an owned tenant profile
PUT/api/management/tenants/{tenant_id}Rename an owned tenant
PUT/api/management/tenants/{tenant_id}/defaultsReplace the tenant routing defaults
DELETE/api/management/tenants/{tenant_id}/provider-keys/{provider}Remove provider settings and a provider credential
PUT/api/management/tenants/{tenant_id}/provider-keys/{provider}Verify and save provider settings and a provider credential
POST/api/management/tenants/{tenant_id}/provider-keys/{provider}/revealReveal one saved provider credential
POST/api/management/tenants/{tenant_id}/secretsGenerate and replace the tenant client secret
GET/api/management/tenants/{tenant_id}/usageRead interval-scoped usage for an owned tenant
GET/api/management/tenants/{tenant_id}/usage/failuresRead safe failure details for an owned tenant and interval
GET/api/management/usageRead interval-scoped usage across every owned tenant
GET/api/management/usage/failuresRead safe failure details across every owned tenant and interval
GET/api/public/capabilitiesRead the public normalized model capability catalog
GET/config-ui.yamlRead the browser runtime configuration
POST/dictateTranscribe an audio upload
POST/model/v1/assetsUpload exact tenant media bytes
DELETE/model/v1/assets/{asset_id}Delete one tenant asset
POST/v2Generate text from canonical messages
/
getText
Generate text from a query prompt
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
prompt | query | Yes | string | User prompt. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
web_search | query | No | boolean | Exact boolean query parameter. Use true or false; omission disables web search. Any other supplied spelling is invalid and returns HTTP 400. |
system_prompt | query | No | string | |
max_tokens | query | No | integer | Initial per-attempt output budget. The same budget is reused when the proxy requests a missing suffix; after a zero-text output-budget stop, a configured model output limit bounds any generic increase. |
reasoning_effort | query | No | string | Non-blank effort supported by the resolved route. Omission selects the tenant or route default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens | Complete generated text in the selected representation. The selected model has one validated wire contract and one execution lifecycle; no lifecycle is inferred from an endpoint or upstream id. The proxy internally observes queued and in_progress states for OpenAI Responses and background-capable Gemini Interactions while keeping every public operation blocking; synchronous Gemini Interactions must return an immediate terminal state. Separately, it continues exact output-budget stops through new provider calls: OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, Gemini Interactions incomplete, and Anthropic max_tokens. HTTP 200 is returned only after the adapter reports its complete signal: OpenAI or Gemini completed, Chat stop, or Anthropic end_turn|stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states never return text as success. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
403 | text/plain | none | The tenant client key is absent or unknown. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider failed, returned a non-429 unsuccessful HTTP status, or returned an unusable success payload. Output-budget stops are continued internally and do not create this response. The response contains only sanitized provider metadata and never exposes partial generated text, token-count headers, a raw provider body, or a provider error message; provider-reported usage can still be retained in managed failure accounting. |
503 | text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The selected provider is not configured or the bounded request queue is full. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/
postText
Generate text from a prompt or messages JSON body
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
prompt | No | string | |
messages | No | array<ChatMessage> | |
model | No | string | |
web_search | No | boolean | |
system_prompt | No | string | |
max_tokens | No | integer | Initial per-attempt output budget. Reused for missing-suffix attempts, with any zero-progress increase bounded by the configured model output limit. |
reasoning_effort | No | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens | Complete generated text in the selected representation. The selected model has one validated wire contract and one execution lifecycle; no lifecycle is inferred from an endpoint or upstream id. The proxy internally observes queued and in_progress states for OpenAI Responses and background-capable Gemini Interactions while keeping every public operation blocking; synchronous Gemini Interactions must return an immediate terminal state. Separately, it continues exact output-budget stops through new provider calls: OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, Gemini Interactions incomplete, and Anthropic max_tokens. HTTP 200 is returned only after the adapter reports its complete signal: OpenAI or Gemini completed, Chat stop, or Anthropic end_turn|stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states never return text as success. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
403 | text/plain | none | The tenant client key is absent or unknown. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider failed, returned a non-429 unsuccessful HTTP status, or returned an unusable success payload. Output-budget stops are continued internally and do not create this response. The response contains only sanitized provider metadata and never exposes partial generated text, token-count headers, a raw provider body, or a provider error message; provider-reported usage can still be retained in managed failure accounting. |
503 | text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The selected provider is not configured or the bounded request queue is full. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/api/management/account
getManagementAccount
Read the authenticated user and owned tenant summaries
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Authenticated account snapshot. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/management/admin/users
getManagementAdminUsers
Read the administrative user and tenant usage summary
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | none | Administrative user and tenant usage summary. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants
createManagementTenant
Create an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | Cache-Control | Created tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
deleteManagementTenant
Delete an owned non-final tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | none | Tenant deleted. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
getManagementTenant
Read an owned tenant profile
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}
renameManagementTenant
Rename an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
name | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/defaults
putManagementTenantDefaults
Replace the tenant routing defaults
Every nonempty provider/model pair must use a provider for which this tenant has a saved API key. The text pair is empty only when no provider key exists. The dictation pair is empty when no keyed provider supports dictation.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
provider | Yes | string | Canonical keyed text-provider id, or empty together with model when the tenant has no saved provider key. |
model | Yes | string | Canonical model for provider, or empty together with provider when the tenant has no saved provider key. |
dictation_provider | Yes | string | Canonical keyed dictation-capable provider id, or empty together with dictation_model when no keyed provider supports dictation. |
dictation_model | Yes | string | Canonical model for dictation_provider, or empty together with dictation_provider when no keyed provider supports dictation. |
system_prompt | Yes | string | |
reasoning_effort | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/provider-keys/{provider}
deleteManagementProviderKey
Remove provider settings and a provider credential
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/provider-keys/{provider}
putManagementProviderKey
Verify and save provider settings and a provider credential
A nonempty api_key performs exactly one provider-authenticated verification operation for the selected provider, text model, and provider base URL under the management request context and shared upstream admission/rate-limit boundary. Changing a saved DashScope base_url also verifies the retained key against the new URL. Only a successful verification atomically persists the credential and submitted settings, reconciles routing defaults, and returns a keyed profile. Rejection and unconfirmed transient outcomes never mutate the provider key, settings, defaults, or managed usage. An empty api_key retains the existing verified credential. The operation returns 409 without a mutation if that retained credential changes before the verified update can persist.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
api_key | Yes | string | An unverified new or replacement provider key. A nonempty value is verified against the exact path provider, selected text_model, and submitted base_url before any persistence. Send an empty string to retain the tenant's existing verified credential; an empty value is rejected when no credential exists. |
base_url | Yes | string | Exact tenant-owned Singapore Model Studio URL for dashscope. It must use https://{resource-id}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. It must be empty for every other provider. |
text_model | Yes | string | |
system_prompt | Yes | string |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current tenant profile. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
409 | text/plain | none | The requested tenant name conflicts, the final owned tenant cannot be deleted, or a retained provider credential changed after verification began. |
415 | none | none | A management mutation did not supply application/json. |
422 | text/plain | none | The candidate credential was rejected or cannot access the selected text model. Nothing was saved. |
429 | text/plain | none | The provider rate-limited the single verification operation. The credential remains unconfirmed and nothing was saved. |
500 | text/plain | none | The management operation failed internally. |
503 | text/plain | none | The provider was unavailable or returned a malformed success envelope. The credential remains unconfirmed and nothing was saved. |
504 | text/plain | none | The single verification operation timed out or was canceled. The credential remains unconfirmed and nothing was saved. |
/api/management/tenants/{tenant_id}/provider-keys/{provider}/reveal
revealManagementProviderKey
Reveal one saved provider credential
This credentialed action requires the exact configured public Origin in addition to the TAuth session.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
provider | path | Yes | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. |
Origin | header | Yes | string | Must exactly match the configured public origin. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The saved provider credential. Never persist or log this response. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/secrets
postManagementTenantSecret
Generate and replace the tenant client secret
Authentication: TAuthSession (cookie app_session_llm_proxy)
Required Content-Type: application/json
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | The newly generated tenant client secret and current profile. The secret is returned only by this response. |
401 | none | none | The TAuth session is absent or invalid. |
403 | none | none | The user lacks the required role or the supplied Origin is not allowed. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
415 | none | none | A management mutation did not supply application/json. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/usage
getManagementTenantUsage
Read interval-scoped usage for an owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
interval | query | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Usage summary for the exact requested interval and authenticated reporting scope. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/tenants/{tenant_id}/usage/failures
getManagementTenantUsageFailures
Read safe failure details for an owned tenant and interval
Returns a newest-first snapshot page of failed managed proxy events. Rows expose only bounded diagnostic metadata and canonical outcome codes; they never include prompts, responses, provider bodies, free-form errors, credentials, or ownership identifiers. Historical rows use status-derived normalized outcome codes rather than reconstructed error messages.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
tenant_id | path | Yes | string | Opaque tenant identifier from the authenticated account response. |
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe tenant failure details for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
404 | none | none | The tenant or provider credential does not exist within the authenticated ownership boundary. |
500 | text/plain | none | The management operation failed internally. |
/api/management/usage
getManagementAccountUsage
Read interval-scoped usage across every owned tenant
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
interval | query | Yes | string | |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Usage summary for the exact requested interval and authenticated reporting scope. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/management/usage/failures
getManagementAccountUsageFailures
Read safe failure details across every owned tenant and interval
Returns a newest-first snapshot page of failed managed proxy events across every tenant owned by the authenticated user. Each row identifies its tenant by opaque ID and current name while exposing only bounded diagnostic metadata and canonical outcome codes. Rows never include prompts, responses, provider bodies, free-form errors, credentials, or another user's ownership data.
Authentication: TAuthSession (cookie app_session_llm_proxy)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
interval | query | Yes | string | |
limit | query | No | integer | Maximum failure rows in this page. Omission selects 25. |
cursor | query | No | string | Opaque continuation cursor returned by the preceding page for the same interval and reporting scope. |
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Snapshot page of safe failure details across every owned tenant for the exact requested interval. |
400 | text/plain | none | Malformed or invalid management input. |
401 | none | none | The TAuth session is absent or invalid. |
500 | text/plain | none | The management operation failed internally. |
/api/public/capabilities
getPublicCapabilities
Read the public normalized model capability catalog
Returns the deterministic, secret-free projection of model publishers, families, exact models, provider offerings, and public proxy request limits.
Authentication: None
Parameters
None.
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | Cache-Control | Current public capability catalog. |
/config-ui.yaml
getBrowserConfiguration
Read the browser runtime configuration
Authentication: None
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
Origin | header | No | string | When supplied, must exactly match the configured public origin for mutations. Matching origins receive credentialed CORS headers. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/yaml | Cache-Control | Current browser runtime configuration. |
/dictate
postDictation
Transcribe an audio upload
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
model | query | No | string | Model identifier. Omission uses the resolved provider default. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
audio | Yes | string | The canonical incoming audio file part. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | Transcription result. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The request is malformed, names an invalid route/capability, or supplies an invalid timeout. Text validation failures use the canonical plain-text error. Timeout-header validation uses the canonical JSON error. |
403 | text/plain | none | The tenant client key is absent or unknown. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider failed, returned a non-429 unsuccessful HTTP status, or returned an unusable success payload. Output-budget stops are continued internally and do not create this response. The response contains only sanitized provider metadata and never exposes partial generated text, token-count headers, a raw provider body, or a provider error message; provider-reported usage can still be retained in managed failure accounting. |
503 | text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The selected provider is not configured or the bounded request queue is full. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/model/v1/assets
uploadTenantAsset
Upload exact tenant media bytes
Stores one hash-bound image or audio asset for the configured retention period. The authenticated tenant owns the returned opaque asset id.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
X-LLM-Proxy-Asset-SHA256 | header | Yes | string | Lowercase hexadecimal SHA-256 of the exact request body. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
201 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset is available to its authenticated tenant. |
400 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
403 | text/plain | none | The tenant client key is absent or unknown. |
413 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
499 | none | none | The caller canceled or closed the request. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |
/model/v1/assets/{asset_id}
deleteTenantAsset
Delete one tenant asset
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
asset_id | path | Yes | string | Opaque tenant asset identifier. |
Request body
None.
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
204 | none | none | The asset is deleted. |
403 | text/plain | none | The tenant client key is absent or unknown. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
410 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
/v2
postV2Messages
Generate text from canonical messages
The current messages-only operation. `messages` is required. User messages may include ordered inline or tenant-asset-backed image and audio attachments. `model`, `web_search`, `max_tokens`, and `reasoning_effort` are optional. Omitting `reasoning_effort` selects the tenant or route default. A supplied value must be non-blank and supported by the resolved route. The selected provider offering owns media admission and transport limits. Unsupported media or route capabilities return HTTP 400 before an upstream call. The service rejects an encoded request body above 8 MiB before JSON decoding. A smaller catalog-derived body limit applies when configured. Current Moonshot Kimi image routes preserve attachment order and exact bytes through Chat Completions Data URL blocks.
Authentication: TenantClientKey (query key)
Parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
key | query | Yes | string | Tenant client secret. |
provider | query | No | string | Canonical provider identifier from the public capability catalog, such as zai. Retired zhipu and glm values are invalid. Omission uses the tenant default. |
format | query | No | string | Preferred response media type. Unknown values select text/plain. |
Accept | header | No | string | Response media preference used when format is omitted. |
X-LLM-Proxy-Request-Timeout-Seconds | header | No | integer | A positive whole-second request budget no greater than the server maximum. Omission selects the configured default. |
Request fields
| Field | Required | Type | Description |
|---|---|---|---|
messages | Yes | array<V2ChatMessage> | All messages must have an allowed role and non-blank content, include at least one user message, and either all omit order or all provide unique non-negative order values. Only user messages may carry attachments; message order and attachment order are preserved. |
model | No | string | Omission selects the resolved provider default. |
web_search | No | boolean | The resolved route must declare web-search capability when true. |
max_tokens | No | integer | Initial per-attempt output budget. Reused for missing-suffix attempts, with any zero-progress increase bounded by the configured model output limit. |
reasoning_effort | No | string | Omission selects the tenant or route default. An explicit value must be non-blank and supported by the resolved provider/model route. Kimi K3 accepts low, high, or max. |
Responses
| Status | Content types | Headers | Description |
|---|---|---|---|
200 | text/plain, application/json, application/xml, text/csv | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-Tokens, X-LLM-Proxy-Response-Tokens, X-LLM-Proxy-Total-Tokens | Complete generated text in the selected representation. The selected model has one validated wire contract and one execution lifecycle; no lifecycle is inferred from an endpoint or upstream id. The proxy internally observes queued and in_progress states for OpenAI Responses and background-capable Gemini Interactions while keeping every public operation blocking; synchronous Gemini Interactions must return an immediate terminal state. Separately, it continues exact output-budget stops through new provider calls: OpenAI Responses incomplete/max_output_tokens, OpenAI-compatible Chat Completions length, Gemini Interactions incomplete, and Anthropic max_tokens. HTTP 200 is returned only after the adapter reports its complete signal: OpenAI or Gemini completed, Chat stop, or Anthropic end_turn|stop_sequence. Intermediate, safety, refusal, tool, malformed, missing, and unknown states never return text as success. |
400 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The canonical message input or referenced asset is invalid. |
403 | text/plain | none | The tenant client key is absent or unknown. |
404 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
410 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
413 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The compatibility JSON request limit, dictation audio limit, tenant asset limit, or selected provider media limit was exceeded. |
429 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider returned HTTP 429. The proxy preserves 429 at its public boundary and returns only sanitized provider metadata; it never exposes the raw provider body or message. |
499 | none | none | The caller canceled or closed the request. |
500 | application/json | X-LLM-Proxy-Request-Timeout-Seconds | The asset operation failed with a stable safe code. |
502 | application/json | X-LLM-Proxy-Request-Timeout-Seconds, X-LLM-Proxy-Request-ID, Retry-After | The selected upstream provider failed, returned a non-429 unsuccessful HTTP status, or returned an unusable success payload. Output-budget stops are continued internally and do not create this response. The response contains only sanitized provider metadata and never exposes partial generated text, token-count headers, a raw provider body, or a provider error message; provider-reported usage can still be retained in managed failure accounting. |
503 | text/plain | X-LLM-Proxy-Request-Timeout-Seconds | The selected provider is not configured or the bounded request queue is full. |
504 | text/plain, application/json | X-LLM-Proxy-Request-Timeout-Seconds | The proxy request budget or upstream operation timed out. |