Skip to main content
A model plugin describes itself with two entities: a Provider that handles authentication and lists supported models, and one AIModelEntity per model declaring its type, features, and parameters.
All entities below are Pydantic BaseModel subclasses from the dify_plugin.entities.model module.

​
Quick Decision

Authentication only: predefined models

User pastes an API key, gets your full model list. Set configurate_methods: [predefined-model] and define each model’s AIModelEntity in YAML.

User-supplied models

User configures their own model name and base URL (OpenAI-compatible endpoints, custom deployments). Use configurate_methods: [customizable-model] and see Customizable Model.

Mixed

Built-in catalog plus user-added custom models. Combine both configurate_methods values.

Walkthrough

For an end-to-end example, see Creating a New Model Provider.

​
Provider

​
string
Provider identifier, for example openai.
​
object
Provider display name (i18n). Supports en_US (English) and zh_Hans (Chinese).
​
string
Chinese label. Falls back to en_US if not set.
​
string
required
English label
​
object
Provider description (i18n).
​
string
Chinese description.
​
string
required
English description.
​
object
Small provider icon, stored in the _assets directory under the provider implementation directory.
​
string
Chinese icon.
​
string
required
English icon.
​
object
Large provider icon, stored in the _assets directory under the provider implementation directory.
​
string
Chinese icon.
​
string
required
English icon.
​
string
Background color value, for example #FFFFFF. If empty, the frontend default color is used.
​
object
Help information.
​
object
Help title (i18n).
​
string
Chinese title.
​
string
required
English title.
​
object
Help link (i18n).
​
string
Chinese link.
​
string
required
English link.
​
array[ModelType]
required
Supported model types.
​
array[ConfigurateMethod]
required
Configuration methods.
​
ProviderCredentialSchema
required
Provider credential specification.
​
ModelCredentialSchema
Model credential specification.

​
AIModelEntity

​
string
required
Model identifier, for example gpt-3.5-turbo.
​
object
Model display name (i18n). Supports en_US (English) and zh_Hans (Chinese).
​
string
Chinese label.
​
string
required
English label.
​
ModelType
required
Model type.
​
array[ModelFeature]
Supported features.
​
object
required
Model properties.
​
LLMMode
Mode (model type llm).
​
integer
Context size (model types llm and text-embedding).
​
integer
Maximum number of chunks (model types text-embedding and moderation).
​
integer
Maximum file upload size in MB (model type speech2text).
​
string
Supported file extensions, for example mp3,mp4 (model type speech2text).
​
string
Default voice; one of alloy, echo, fable, onyx, nova, shimmer (model type tts).
​
array
Available voices (model type tts).
​
string
Voice model.
​
string
Voice model display name.
​
string
Languages the voice model supports.
​
integer
Word limit per conversion; defaults to splitting by paragraph (model type tts).
​
string
Supported audio file extensions, for example mp3,wav (model type tts).
​
integer
Number of concurrent text-to-audio conversion tasks (model type tts).
​
integer
Maximum characters per chunk (model type moderation).
​
array[ParameterRule]
Rules for model call parameters.
​
PriceConfig
Pricing information.
​
boolean
Whether the model is deprecated. Deprecated models no longer appear in the model list, but existing configurations keep working. Defaults to False.

​
ModelType

​
string
Text generation model.
​
string
Text embedding model.
​
string
Rerank model.
​
string
Speech to text.
​
string
Text to speech.
​
string
Content moderation.

​
ConfigurateMethod

​
string
Predefined model. The user configures unified provider credentials once to use all predefined models under the provider.
​
string
Customizable model. The user adds a credential configuration for each model.
​
string
Fetch from remote. Like predefined-model, only unified provider credentials are needed, but the model list is fetched from the provider using those credentials.

​
ModelFeature

​
string
Agent reasoning. Generally, models over 70B have chain-of-thought capabilities.
​
string
Vision (image understanding).
​
string
Tool calling.
​
string
Multiple tool calling.
​
string
Streaming tool calling.

​
FetchFrom

​
string
Predefined model.
​
string
Remote model.

​
LLMMode

​
string
Text completion.
​
string
Chat.

​
ParameterRule

​
string
required
Actual parameter name used in the model call.
​
string
Template to use.
Five parameter templates are predefined:
  • temperature
  • top_p
  • frequency_penalty
  • presence_penalty
  • max_tokens
Set one of these names in use_template to inherit the default configuration from entities.defaults.PARAMETER_RULE_TEMPLATE; you then only need name and use_template. Any additional parameters you set override the template defaults. See openai/llm/gpt-3.5-turbo.yaml and the examples in Creating a New Model Provider.
​
object
Label (i18n).
​
string
Chinese label.
​
string
required
English label.
​
string
Parameter type.
​
string
Integer.
​
string
Floating point.
​
string
String.
​
string
Boolean.
​
object
Help information (i18n).
​
string
Chinese help text.
​
string
required
English help text.
​
boolean
Whether the parameter is required. Defaults to False.
​
int/float/string/boolean
Default value.
​
int/float
Minimum value. Numeric types only.
​
int/float
Maximum value. Numeric types only.
​
integer
Number of decimal places to keep. Numeric types only.
​
array[string]
Dropdown option values. Only applies when type is string. If not set or null, values are unrestricted.

​
PriceConfig

​
float
Input (prompt) unit price.
​
float
Output (returned content) unit price.
​
float
Price unit. For example, if pricing is per 1M tokens, the unit token count corresponding to the unit price is 0.000001.
​
string
Currency unit.

​
ProviderCredentialSchema

​
array[CredentialFormSchema]
required
Credential form specification.

​
ModelCredentialSchema

​
object
required
Model identifier. The default variable name is model.
​
object
required
Display name of the model form item.
​
string
required
English.
​
string
Chinese.
​
object
required
Placeholder text for the model form item.
​
string
required
English.
​
string
Chinese.
​
array[CredentialFormSchema]
required
Credential form specification.

​
CredentialFormSchema

​
string
required
Form item variable name.
​
object
required
Form item label.
​
string
required
English.
​
string
Chinese.
​
FormType
required
Form item type.
​
boolean
Whether the form item is required.
​
string
Default value.
​
array[FormOption]
Dropdown content. Specific to the select and radio types.
​
object
Form item placeholder. Specific to the text-input type.
​
string
required
English.
​
string
Chinese.
​
integer
Maximum input length. Specific to the text-input type. 0 means no limit.
​
array[FormShowOnObject]
Show this item only when other form item values meet the given conditions. Empty means always show.

​
FormType

​
string
Text input component.
​
string
Password input component.
​
string
Single-select dropdown.
​
string
Radio component.
​
string
Switch component. Only supports true and false.

​
FormOption

​
object
required
Label.
​
string
required
English.
​
string
Chinese.
​
string
required
Dropdown option value.
​
array[FormShowOnObject]
Show this option only when other form item values meet the given conditions. Empty means always show.

​
FormShowOnObject

​
string
required
Variable name of the other form item.
​
string
required
Variable value of the other form item.
Last modified on June 24, 2026