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 25, 2026