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

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

​
AIModelEntity

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

​
ModelType

​
llm
string
Text generation model.
​
text-embedding
string
Text embedding model.
​
rerank
string
Rerank model.
​
speech2text
string
Speech to text.
​
tts
string
Text to speech.
​
moderation
string
Content moderation.

​
ConfigurateMethod

​
predefined-model
string
Predefined model. The user configures unified provider credentials once to use all predefined models under the provider.
​
customizable-model
string
Customizable model. The user adds a credential configuration for each model.
​
fetch-from-remote
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

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

​
FetchFrom

​
predefined-model
string
Predefined model.
​
fetch-from-remote
string
Remote model.

​
LLMMode

​
completion
string
Text completion.
​
chat
string
Chat.

​
ParameterRule

​
name
string
required
Actual parameter name used in the model call.
​
use_template
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.
​
label
object
Label (i18n).
​
zh_Hans
string
Chinese label.
​
en_US
string
required
English label.
​
type
string
Parameter type.
​
int
string
Integer.
​
float
string
Floating point.
​
string
string
String.
​
boolean
string
Boolean.
​
help
object
Help information (i18n).
​
zh_Hans
string
Chinese help text.
​
en_US
string
required
English help text.
​
required
boolean
Whether the parameter is required. Defaults to False.
​
default
int/float/string/boolean
Default value.
​
min
int/float
Minimum value. Numeric types only.
​
max
int/float
Maximum value. Numeric types only.
​
precision
integer
Number of decimal places to keep. Numeric types only.
​
options
array[string]
Dropdown option values. Only applies when type is string. If not set or null, values are unrestricted.

​
PriceConfig

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

​
ProviderCredentialSchema

​
credential_form_schemas
array[CredentialFormSchema]
required
Credential form specification.

​
ModelCredentialSchema

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

​
CredentialFormSchema

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

​
FormType

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

​
FormOption

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

​
FormShowOnObject

​
variable
string
required
Variable name of the other form item.
​
value
string
required
Variable value of the other form item.
Edit this page | Report an issue