> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Specs

> Reference for the entities that define a Dify model plugin, including Provider, AIModelEntity, model types, configuration methods, parameter rules, and credential schemas

A model plugin describes itself with two entities: a [Provider](#provider) that handles authentication and lists supported models, and one [AIModelEntity](#aimodelentity) per model declaring its type, features, and parameters.

> [!NOTE]
>
> All entities below are `Pydantic BaseModel` subclasses from the `dify_plugin.entities.model` module.

## Quick Decision

> [card] 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.

> [card] 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/features-and-specs/advanced-development/customizable-model.md).

> [card] Mixed
>
> Built-in catalog plus user-added custom models. Combine both `configurate_methods` values.

> [card] Walkthrough
>
> For an end-to-end example, see [Creating a New Model Provider](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/dev-guides-and-walkthroughs/creating-new-model-provider.md).

## 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/dev-guides-and-walkthroughs/creating-new-model-provider.md).

**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.

## Related Resources

* [Model Architecture Details](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/features-and-specs/plugin-types/model-schema.md)—architecture specifications for model plugins
* [Quickly Integrate a New Model](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/dev-guides-and-walkthroughs/creating-new-model-provider.md)—apply these rules to add new models
* [General Specifications](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/features-and-specs/plugin-types/general-specifications.md)—plugin manifest configuration
* [Create a New Model Provider](https://enterprise-docs.dify.ai/en/3.13.x/develop/plugins/dev-guides-and-walkthroughs/creating-new-model-provider.md)—develop a new model provider plugin


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.