AI Models

AI Models are tenant-side external model resources. They provide the model credentials and runtime configuration used by Soln features that call chat, vision, tool-calling, image generation, or image-input models.

Open System > Resource, then select AI Models from the resource menu.

Page Structure

The AI Models page has three main areas:

Area	Purpose
Top Bar	Searches models, creates model categories, filters models by all, active, or disabled status, and opens Model Usage
Category List	Groups models by provider or scenario and shows how many models are in each category. The footer provides the Model Billing entry
Model List	Shows models in the selected category and provides edit, enable, disable, delete, and create-from-this-config actions

Model Categories

Use model categories to keep models organized by provider, purpose, or runtime scenario.

Field	Description
Model Icon	Category icon. Upload an image so the category is easy to recognize in the model list
Model Category Name	Display name of the category, such as OpenAI, Gemini, Image Models, or Internal Gateway

Category actions:

Action	Description
New Model Category	Creates a custom category
Edit	Updates a custom category name or icon
Delete	Deletes the custom category and clears models in that category
New	Creates a model under the selected category

Preset categories can appear in the list. They can be selected and used for creating models, but only custom categories can be edited or deleted.

Create An AI Model

Click New in the selected category, then fill in the model connection fields.

Field	Required	Description
Model Type	Yes	Selects Text model or Image generation model. The model type limits which protocols can be selected and decides whether the runtime uses the resource for chat or image generation
Protocol	Yes	Model API protocol used by Soln. The protocol decides the default Base URL, the request endpoints, and the model capabilities written to the resource
Base URL	Yes	Provider base endpoint used by the selected protocol. Changing the protocol fills a matching default URL when the current URL is empty or still uses a known default. OpenAI-compatible gateways should use the gateway root URL, not a `/chat/completions` path
API Key	Yes when creating	Secret credential used to call the provider. When editing an existing model, leave it empty to keep the stored key unchanged
Model	Yes	Provider model identifier, such as `gpt-5.6`, `gpt-image-2`, `claude-opus-4-8`, `gemini-3.6-flash`, or the model name from your gateway. The model name cannot be changed after the model is created, so billing, usage statistics, and audit records stay consistent
Model Display Name	Yes	Name shown to administrators and runtime selectors. Use a name that explains the provider, account, and purpose
Config (JSON)	No	Extra JSON object merged into the model config. Use it for provider-specific options that are not represented by the standard fields

Protocols

Choose the provider protocol that matches the model service. The runtime selects the official AI SDK provider from the selected protocol.

Protocol	Model Type	Default Base URL	Typical Use
OpenAI Responses	Text model	`https://api.openai.com/v1`	OpenAI Responses-compatible services. Soln sends chat and built-in image-generation tool requests to the `/responses` endpoint
OpenAI Chat Completions	Text model	`https://api.openai.com/v1`	OpenAI Chat Completions-compatible services. Soln sends chat requests to the `/chat/completions` endpoint
Anthropic Messages	Text model	`https://api.anthropic.com/v1`	Anthropic Claude chat, vision, and tool-calling models through the native `/messages` endpoint
Google Gemini GenerateContent	Text model	`https://generativelanguage.googleapis.com/v1beta`	Google Gemini chat, vision, and tool-calling models through the native GenerateContent API
OpenAI Images	Image Generation Model	`https://api.openai.com/v1`	OpenAI image endpoint. Generates images and supports editing from input images
xAI Grok Images	Image Generation Model	`https://api.x.ai/v1`	xAI Grok image endpoint. Generates images and supports editing from input images
Google Imagen	Image Generation Model	`https://generativelanguage.googleapis.com/v1beta`	Google Imagen image generation endpoint. Generates images only; image editing is not supported
Google Gemini Images	Image Generation Model	`https://generativelanguage.googleapis.com/v1beta`	Native Gemini image generation endpoint. Generates images and supports editing from input images

Changing the protocol replaces the Base URL with the protocol default when the current URL is empty or still uses a known default. The actual URL for an OpenAI-compatible gateway depends on the provider deployment.

Model Capabilities

Model capabilities are derived from Model Type and Protocol and written to the model resource capability metadata. The form does not expose a separate capability selector.

Capability	Derived From	Description
Chat	Text model protocols	The resource is used for assistant conversation and text generation
Streaming	Text model protocols	Text models return incremental content as a stream
Image Input / Vision	Text model protocols	Chat messages can include images. Use this only when the model and gateway both accept image messages
Tool Calling	Text model protocols	Soln uses this for assistant workflows that need tenant data tools, form tools, file tools, or other runtime actions
Image Generation	Image generation model protocols	The resource is used to generate images
Image Editing	Image protocols that support editing	OpenAI Images, xAI Grok Images, and Google Gemini Images can edit an existing image; Google Imagen cannot

Image generation models are never used for chat, so an image generation resource never carries streaming or tool-calling capabilities.

Vision capability must match the model
Text model protocols write the image-input capability flag. If a text-only model is configured, image questions may be rejected by the provider before Soln can generate an answer. Use a vision-capable model instead.

Image Generation And Editing

Image requests use resources whose model type is Image Generation Model. Only protocols that support image editing can modify an existing image in the assistant.

Protocol	Generate Images	Edit Images
OpenAI Images	Yes	Yes
xAI Grok Images	Yes	Yes
Google Gemini Images	Yes	Yes
Google Imagen	Yes	No

In the assistant, choose Create Image. A text-only message generates a new image; attaching one or more PNG, JPEG, WEBP, or non-animated GIF images to the current message changes that request to image editing. The current assistant does not provide a mask upload field.

Config JSON

The Config (JSON) field must be a JSON object. Use it for standard generation settings and provider-specific request parameters that are not represented by the form. Select the matching Protocol first, then use the field names and values documented by that provider or gateway. Soln does not infer settings from the model name.

The Config JSON is merged into the stored model config together with standard fields such as protocol, baseUrl, and model. It cannot replace fields controlled by the form.

Reserved keys:

Key	Description
`protocol`	Written from the Protocol field. Do not set it in Config JSON
`baseUrl`	Written from the Base URL field. Do not set it in Config JSON
`model`	Written from the Model field. Do not set it in Config JSON
`toolCalling`	Derived from Model Type and Protocol. Do not set it in Config JSON
`toolDiscovery`	Controlled by the assistant runtime. Do not set it in Config JSON
`contextWindowTokens`	Not configurable. Do not set it in Config JSON

Context window size is not configurable in model resources. The tenant Runtime maintains conversation checkpoints automatically, preserving original user instructions and references to execution evidence. Recent messages remain intact; older execution details can be read through Runtime commands. Checkpoint scheduling is an internal maintenance policy, not a configurable model capacity limit.

Standard Generation Settings

These top-level settings are mapped to the AI SDK generation call:

Parameter	Description
`temperature`	Sampling temperature. The provider decides the supported range
`topP`	Nucleus sampling value
`maxTokens`	Maximum output token count
`presencePenalty`	Penalty for introducing topics already present in the generated text
`frequencyPenalty`	Penalty based on repeated token frequency

Only configure settings supported by the selected provider and model. Capability flags such as streaming, tool calling, image input, and image generation are derived from Model Type and Protocol; do not configure them in Config JSON.

Example:

{
  "temperature": 0.7,
  "topP": 0.9,
  "maxTokens": 4096
}

Provider-Specific Parameters

Use these generic keys when the selected protocol exposes settings that are not represented by the standard generation fields:

Key	Value	Behavior
`headers`	Object	Adds provider or gateway request headers. Header values are converted to strings
`requestBody`	Object	Adds protocol-specific fields to the final JSON request body. Nested objects are merged recursively; explicit configured values override AI SDK defaults unless the field is reserved by Soln Runtime
`providerTools`	Array of objects	Enables provider-executed tools registered by Soln. Each item contains a registered `id` and an optional `options` object

Use this decision order when filling in Config JSON:

Put temperature, topP, maxTokens, presencePenalty, and frequencyPenalty at the top level
When provider documentation defines another request-body field, keep its original name and nesting under requestBody
When you need a provider-executed tool, select its registered ID from the table below and place it in providerTools
Use headers only for additional provider or gateway headers. Keep the API key in the dedicated API Key field

Field placement reference:

Requirement	Config JSON location
Standard sampling or output limit	Top-level generation setting, such as `temperature` or `maxTokens`
Additional top-level provider body field	`requestBody.<provider field>`
Additional nested provider body field	Preserve the full nesting under `requestBody`
Provider web search or another registered server-side tool	`providerTools[].id` and `providerTools[].options`
Additional HTTP header	`headers.<header name>`

The same request-body passthrough is used by every supported protocol. Soln does not inspect the model name, translate parameter names between protocols, or maintain an allowlist of provider request fields. Consult the selected provider or gateway documentation and configure only fields accepted by that endpoint.

For requestBody, object values are merged recursively. Explicit scalar and array values replace the corresponding AI SDK defaults. Request identity, conversation state, credentials, streaming, and tool orchestration remain controlled by Soln Runtime and cannot be overridden. Protected fields include model, messages, input, contents, prompt, system, systemInstruction, instructions, stream, tools, tool_choice, toolConfig, store, conversation, previous_response_id, background, apiKey, api_key, baseUrl, and base_url.

Provider Tools

providerTools are server-side tools executed by the model provider. Soln creates them through the matching AI SDK provider tool factory before calling streamText(), then combines them with the Assistant Runtime tools passed to the model. Only text model protocols derive the tool-calling capability, so this setting applies to text models only.

Each providerTools item accepts only these fields:

Field	Required	Description
`id`	Yes	Registered provider tool identifier. The tool must belong to the selected protocol
`options`	No	Configuration passed to the registered AI SDK provider tool factory. Supported fields depend on the tool ID

Registered tools:

Tool ID	Protocol	Purpose and options
`openai.web_search`	OpenAI Responses	Web search. Options control external web access, allowed-domain filters, search context size, and approximate user location
`anthropic.web_search_20260209`	Anthropic Messages	Web search. Options control maximum uses, allowed or blocked domains, and approximate user location
`google.google_search`	Google Gemini GenerateContent	Google Search grounding. Options control enabled search types and an optional time range

Supported options fields:

Tool ID	Option	Type	Purpose
`openai.web_search`	`externalWebAccess`	Boolean	Selects live external web access or provider-cached/indexed content
`openai.web_search`	`filters.allowedDomains`	String array	Restricts search results to the listed domains
`openai.web_search`	`searchContextSize`	`low`, `medium`, or `high`	Controls search context volume, latency, and cost
`openai.web_search`	`userLocation`	Object	Supplies an approximate country, city, region, and time zone for geographically relevant results
`anthropic.web_search_20260209`	`maxUses`	Number	Limits the number of searches during the conversation
`anthropic.web_search_20260209`	`allowedDomains`	String array	Restricts searches to the listed domains
`anthropic.web_search_20260209`	`blockedDomains`	String array	Excludes the listed domains from searches
`anthropic.web_search_20260209`	`userLocation`	Object	Supplies an approximate country, city, region, and time zone for geographically relevant results
`google.google_search`	`searchTypes`	Object	Enables web search, image search, or both when supported by the selected model
`google.google_search`	`timeRangeFilter`	Object	Restricts results to required ISO 8601 `startTime` and `endTime` values

The following are Soln Config JSON examples, not copies of provider request payloads. Choose only the example whose protocol matches the model resource.

OpenAI Responses web search:

{
  "providerTools": [
    {
      "id": "openai.web_search",
      "options": {
        "externalWebAccess": true,
        "searchContextSize": "medium"
      }
    }
  ]
}

Anthropic Messages web search:

{
  "providerTools": [
    {
      "id": "anthropic.web_search_20260209",
      "options": {
        "maxUses": 5
      }
    }
  ]
}

Google Gemini GenerateContent search grounding:

{
  "providerTools": [
    {
      "id": "google.google_search",
      "options": {
        "searchTypes": {
          "webSearch": {}
        }
      }
    }
  ]
}

To combine generation settings and a provider tool, keep them in the same Config JSON object. For example, add temperature beside providerTools, not inside options.

These tools are not Soln business tools. Tenant data and business actions continue through SL_COMMANDS, executeSlCommand, and the Runtime domain implementation; they are not routed through MCP. Provider tools also cannot be declared through requestBody.tools, because Soln Runtime must retain ownership of tool registration and tool choice.

Do not put secrets in Config JSON. Store credentials in the API Key field so they are saved as resource secrets.

Model Billing

Model billing configures prices for AI models. The estimated cost in call logs and usage analytics, and the cost limits in usage controls, both depend on the billing modes configured here.

Open System > Resource > AI Models, then click Model Billing at the bottom of the category list.

Billing Modes

The left side lists the billing modes created in the current space, and the right side is the billing mode editor.

Action	Description
New	Creates a billing mode
Edit	Updates the billing mode name, currency, billing type, prices, and applicable models
Delete	Permanently deletes the billing mode

Billing Fields

Field	Required	Description
Billing Mode Name	Yes	Display name of the billing mode
Currency	Yes	Supports CNY and USD
Billing Type	Yes	Decides which price fields are required and how cost is calculated from usage
Prices	Yes	Per-million-token or per-image prices, with up to 6 decimal places
Applicable Models	Yes	AI models selected by category. A model can belong to only one billing mode, so models already used by another billing mode cannot be selected again

Billing Types

Billing Type	Typical Use	Price Fields
Input/Output Token Billing	Models billed only by input and output tokens	Input and output, per million tokens
Cached Input Token Billing	Models that distinguish uncached input, cache reads, and cache writes	Input, cached input, cache write (optional), and output, per million tokens
Long Context Token Billing	Models that use a different price above a threshold	Long-context threshold (K tokens); input, cached input, cache write (optional), and output prices for standard and long context
Multimodal Token Billing	Models billed by tokens for both text and images	Text input, cached text input, image input tokens, cached image input, text output, image output tokens, and reasoning output, per million tokens; at least one price is required
Image Generation Billing	Image models billed per generated image	Input image (optional) and one or more output image prices by size, quality, and unit price

Notes:

A model without a billing mode can still be called, but the estimated cost in call logs and usage analytics shows Pricing not configured
Changing a billing mode affects later cost calculations only. Historical call logs keep the cost calculated at the time of the call
Billing modes are currency-specific. A space can have both CNY and USD billing modes, and usage pages show costs per currency

Model Usage

The Model Usage page summarizes model calls, token consumption, cost, and usage controls for the current space. Open it from the Model Usage button in the top bar of System > Resource > AI Models.

Left menu:

Menu	Purpose
Overview	Shows call trends, token composition, category distribution, and model rankings for a time range
Analytics	Aggregates tokens, image counts, and estimated cost by organization and department
Call Logs	Shows every model call in detail
External Calls	Manages the API keys members use to call the model service from outside Soln

Members with resource-edit permission also see Usage Controls in the top-right corner, which opens usage-limit rules and model gateway protection.

Overview

Area	Description
Filters	Time range (last seven days by default), model category, and model. Select a category before selecting one of its models
Metric Cards	Calls, total tokens, active users, success rate, average task duration, cache hit rate, and estimated cost. Cost is shown per currency
Charts	Calls and token trend, input/output/cached tokens, and model category distribution
Model Ranking	Model, calls, tokens, cost, success rate, and average task duration

Charts can be exported as PNG from the panel header, and the model ranking can be exported as an Excel file. When cost is empty or shows -, the model usually has no billing mode, or the call log lacks the usage data required for cost calculation.

Analytics

Analytics groups usage by the organization and department each member currently belongs to, so you can see how tokens, images, and estimated cost are distributed.

Area	Description
Filters	Time range, model category, and model
Metric Cards	Tokens, image count, estimated CNY cost, and estimated USD cost, each with a trend line
Organization/Department Distribution	Treemap of department usage share with a switchable metric and PNG export
Organization/Department Usage	Organization, department, tokens, image count, estimated CNY cost, and estimated USD cost. Supports organization or department filtering, paging, and Excel export
User Usage	User, tokens, image count, estimated CNY cost, and estimated USD cost. Supports user filtering, paging, and Excel export

Call Logs

Call logs list every model call in reverse chronological order, which helps with troubleshooting failed calls and checking cost.

Item	Description
Filters	Start time, end time, calling user, model category, and model. The refresh button reloads the current filter result
Columns	Called at, user, model, category, protocol, tokens, estimated cost, duration, and status
Tokens	Shows input, output, cache read, and cache write token counts separately
Summary	The pagination footer shows cache hit rate and total tokens for the current filter range
Estimated Cost	Calculated from the billing mode. When it cannot be calculated, the log shows Pricing not configured, Usage Incomplete, No Matching Price Rule, or Invalid Price Rule

Cost status:

Status	Meaning	What To Do
Pricing not configured	The model is not bound to any billing mode	Configure prices for the model in Model Billing
Usage Incomplete	The provider response lacks the usage fields required by the current billing type	Check the protocol, model capabilities, and provider response, or use a billing type that matches the returned data
No Matching Price Rule	A billing mode exists, but the usage matched no price tier	Check the billing type, the long-context threshold, and the image size and quality settings
Invalid Price Rule	The billing mode configuration is invalid	Save the billing mode prices again

External Calls

External calls are disabled by default. Administrators with resource-edit permission can enable the external-call switch on this page. While disabled, member account settings hide the AI Key entry and the model gateway rejects external requests, including model listing, with HTTP 403 and MODEL_GATEWAY_EXTERNAL_CALL_DISABLED. Enabling the switch still requires a valid key, an active member, and model access.

External calls manage the API keys members use when they call models through the model service.

Item	Description
Filters	Time range (current week by default) and calling user
Columns	User, key, status, last used at, created at, and updated at
Rotate	Generates a new key for the member. The old key stops working immediately, and the new plaintext key is shown only once
Disable / Enable	Stops or restores the member's ability to call the model service with the key

Calls made through external keys are recorded in call logs and included in usage analytics and usage controls.

Before You Call

First confirm that an administrator has enabled external calls for this tenant.

Get an AI key: Settings > AI Key in the sidebar creates the key of the signed-in member, and an administrator can also rotate the key of a member in Model Usage > External Calls. The key starts with so. and is shown only once
Read the resource key of the model you want to call: System > Resource > AI Models, or GET /api/soln.modelservice/v1/models
Match the protocol of the resource with the endpoint below
Send the call with the key as a credential header

Call Address

External callers use the model service gateway of the workspace, so the address is the workspace address itself plus the soln.modelservice prefix:

https://<workspace-domain>/api/soln.modelservice

The gateway keeps the protocol of the model resource, so pick the endpoint that matches the Protocol of the resource you want to call.

Protocol	Method	Endpoint	Credential header	Required body fields
OpenAI Chat Completions	POST	`/api/soln.modelservice/v1/chat/completions`	`Authorization: Bearer <AI key>`	`model`, `messages`
OpenAI Responses	POST	`/api/soln.modelservice/v1/responses`	`Authorization: Bearer <AI key>`	`model`, `input`
Anthropic Messages	POST	`/api/soln.modelservice/v1/messages`	`x-api-key: <AI key>`	`model`, `messages`, `max_tokens`
Google GenerateContent	POST	`/api/soln.modelservice/v1beta/models/{model}:generateContent`	`x-goog-api-key: <AI key>`	`contents`
Google streaming	POST	`/api/soln.modelservice/v1beta/models/{model}:streamGenerateContent?alt=sse`	`x-goog-api-key: <AI key>`	`contents`
List models	GET	`/api/soln.modelservice/v1/models`	`Authorization: Bearer <AI key>`	None

Anthropic requests may carry anthropic-version and anthropic-beta; without anthropic-version the gateway sends 2023-06-01. When the model resource of the selected protocol does not match the endpoint, the gateway rejects the call with MODEL_GATEWAY_PROTOCOL_INVALID.

The protocol of a model resource and the endpoint are one-to-one. A model resource can only be called through the endpoint of its own protocol, and each protocol uses its own credential header and request body. When the same provider must be reached through two protocols, for example both OpenAI Responses and OpenAI Chat Completions, create one model resource per protocol.

The model Value

model is the resource key of the AI model resource, not the provider model name. Read it in two ways:

System > Resource > AI Models shows the resource key of each model
GET /api/soln.modelservice/v1/models returns the models the key may use, and the resource key is the id of each entry

The gateway replaces model with the provider model configured on the resource before it calls the provider, so callers never need the provider model name. For the Google endpoints the resource key goes into the path instead of the body. GET /v1/models also reports whether a model is currently available and how much quota is left.

curl Examples

List the models of the space:

export SOLN_API_KEY="so.xxxxxxxxxxxxxxxx"
export SOLN_BASE_URL="https://<workspace-domain>/api/soln.modelservice"

curl "$SOLN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $SOLN_API_KEY"

Chat with an OpenAI Chat Completions model:

curl "$SOLN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "messages": [
      { "role": "user", "content": "用一句话介绍 Soln" }
    ],
    "temperature": 0.7
  }'

Stream the answer:

curl -N "$SOLN_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "messages": [
      { "role": "user", "content": "写一段 200 字的说明" }
    ],
    "stream": true
  }'

Call an OpenAI Responses model:

curl "$SOLN_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-abc123",
    "input": "总结这条记录的要点"
  }'

Call an Anthropic Messages model:

curl "$SOLN_BASE_URL/v1/messages" \
  -H "x-api-key: $SOLN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8-abc123",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "用一句话介绍 Soln" }
    ]
  }'

Call a Google Gemini GenerateContent model, where the resource key is part of the address:

curl "$SOLN_BASE_URL/v1beta/models/gemini-3-6-flash-abc123:generateContent" \
  -H "x-goog-api-key: $SOLN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "parts": [ { "text": "用一句话介绍 Soln" } ] }
    ]
  }'

Request And Response Rules

Rule	Description
Content type	Requests must use `Content-Type: application/json`
Body limit	The request body may be at most 8 MB
Response	The provider response is passed back as it is, including streamed Server-Sent Events
Request id	Every response carries an `x-request-id` header that also appears in the call log
Streaming	Send `stream: true` to receive streamed content; the gateway adds `stream_options.include_usage` so the call can be billed
Provider fields	Body fields other than `model` are forwarded to the provider unchanged, so provider-specific parameters can be sent directly
Timeout	The upstream call is aborted after 120 seconds by default and returns `MODEL_GATEWAY_UPSTREAM_TIMEOUT`

Error Responses

Gateway errors use the OpenAI error shape, and provider errors keep the status and body of the provider:

{
  "error": {
    "code": "MODEL_GATEWAY_API_KEY_REQUIRED",
    "message": "MODEL_GATEWAY_API_KEY_REQUIRED",
    "param": null,
    "type": "authentication_error"
  }
}

HTTP	Code	Meaning
400	`MODEL_GATEWAY_MODEL_REQUIRED`, `MODEL_GATEWAY_MESSAGES_REQUIRED`, `MODEL_GATEWAY_INPUT_REQUIRED`, `MODEL_GATEWAY_CONTENTS_REQUIRED`, `MODEL_GATEWAY_MAX_TOKENS_INVALID`	The request body is missing a required field or uses an invalid value
400	`MODEL_GATEWAY_PROTOCOL_INVALID`	The endpoint does not match the protocol of the model resource
400	`MODEL_GATEWAY_CONTENT_TYPE_INVALID`, `MODEL_GATEWAY_BODY_INVALID`	The content type or the JSON body is invalid
401	`MODEL_GATEWAY_API_KEY_REQUIRED`, `MODEL_GATEWAY_API_KEY_INVALID`	The AI key is missing or not valid
403	`MODEL_GATEWAY_MEMBER_INACTIVE`, `MODEL_ACCESS_DENIED`	The member or the key is disabled, or the model is not available to this member
404	Codes ending in `_NOT_FOUND`, for example `MODEL_NOT_FOUND`	The model resource does not exist
413	`MODEL_GATEWAY_BODY_TOO_LARGE`	The request body exceeds 8 MB
429	`MODEL_GATEWAY_RATE_LIMIT_EXCEEDED`, `MODEL_GATEWAY_CONCURRENCY_LIMIT_EXCEEDED`	Model gateway protection rejected the request
504	`MODEL_GATEWAY_UPSTREAM_TIMEOUT`	The provider did not answer before the timeout

Model gateway protection counts requests per AI key: Requests Per Minute defaults to 120 and Maximum Concurrent Requests defaults to 8, and both can be changed in Usage Controls.

Usage Controls

Usage controls limit how much model usage a space, user, role, department, or organization can consume. Click Usage Controls to open the rules page, which shows the rule list on the left and the rule editor on the right.

The rule list contains one Space Global Rule and any number of custom rules:

Rule	Description
Space Global Rule	Applies to every user in the current space, always uses a shared quota, and always covers all AI models
Custom Rule	Configured by applicable scope, applicable models, and limit metrics

Rule fields:

Field	Description
Rule Name	Display name of the rule
Quota Mode	Individual quota: each applicable member gets a separate quota. Shared quota: all applicable members share one quota
Applicable Scope	User, role, department, or organization. Departments and organizations can include descendants
Applicable Models	AI models covered by the rule. When no model is selected, the rule covers all AI models
Period	Daily or monthly
Status	Active or disabled
Limit Metrics	Call count, total tokens, CNY cost, USD cost, and image generation count. Fill in only the metrics that need a limit; leave the others empty for no limit

Limit notes:

Call count, total tokens, and image count use whole numbers. The token limit is entered in millions (M)
CNY and USD cost limits accept an amount with up to 6 decimal places
A custom rule without an applicable scope does not take effect
When one request matches several rules, Match mode decides whether each metric uses the strictest or the loosest limit: Minimum match takes the smallest limit, and Maximum match takes the largest limit

The same page also provides Model Gateway Protection, which limits gateway request rate and concurrency:

Field	Description
Requests Per Minute	Per-API-key request limit in a fixed 60-second window
Maximum Concurrent Requests	Requests above this limit are rejected until an upstream request completes

Status And Deletion

Enabled models are available for runtime use. Disabled models stay configured but should not be selected by runtime features. A model can be deleted after it is disabled.

Common Workflow

Open System > Resource > AI Models
Create or select a model category
Click New in the category
Choose the model type and the protocol that matches the provider endpoint
Fill in Base URL, API Key, model, and model display name
Add optional Config JSON for provider-specific request parameters
Save the model
Enable, disable, edit, or delete models from the model list as needed
Configure prices for the model in Model Billing
Use Model Usage to review call logs, usage analytics, and estimated cost
Configure usage limits and gateway protection in Usage Controls as needed

Page Structure​

Model Categories​

Create An AI Model​

Protocols​

Model Capabilities​

Image Generation And Editing​

Config JSON​

Standard Generation Settings​

Provider-Specific Parameters​

Provider Tools​

Model Billing​

Billing Modes​

Billing Fields​

Billing Types​

Model Usage​

Overview​

Analytics​

Call Logs​

External Calls​

Before You Call​

Call Address​

The model Value​

curl Examples​

Request And Response Rules​

Error Responses​

Usage Controls​

Status And Deletion​

Common Workflow​