Title: PromptBuilder::usingModelPreference
Published: May 20, 2026

---

# PromptBuilder::usingModelPreference( string|WordPressAiClientProvidersModelsContractsModelInterface|WordPressAiClientBuildersarray{0:string,1:string} $preferredModels ): self

## In this article

 * [Parameters](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#wp--skip-link--target)

Sets preferred models to evaluate in order.

## 󠀁[Parameters](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#parameters)󠁿

 `$preferredModels`string|WordPressAiClientProvidersModelsContractsModelInterface
|WordPressAiClientBuildersarray{0:string,1:string}required

The preferred models as model IDs, model instances, or [provider ID, model ID] tuples.
For broader compatibility, it is recommended you specify only model IDs or model
instances, as that will allow for different providers that expose the same model
to be considered.

## 󠀁[Return](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#return)󠁿

 self

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#source)󠁿

    ```php
    public function usingModelPreference(...$preferredModels): self
    {
        if ($preferredModels === []) {
            throw new InvalidArgumentException('At least one model preference must be provided.');
        }
        $preferenceKeys = [];
        foreach ($preferredModels as $preferredModel) {
            if (is_array($preferredModel)) {
                // [model identifier, provider ID] tuple
                if (!array_is_list($preferredModel) || count($preferredModel) !== 2) {
                    throw new InvalidArgumentException('Model preference tuple must contain model identifier and provider ID.');
                }
                [$providerId, $modelId] = $preferredModel;
                $modelId = $this->normalizePreferenceIdentifier($modelId);
                $providerId = $this->normalizePreferenceIdentifier($providerId, 'Model preference provider identifiers cannot be empty.');
                $preferenceKey = $this->createProviderModelPreferenceKey($providerId, $modelId);
            } elseif ($preferredModel instanceof ModelInterface) {
                // Model instance
                $modelId = $preferredModel->metadata()->getId();
                $providerId = $preferredModel->providerMetadata()->getId();
                $preferenceKey = $this->createProviderModelPreferenceKey($providerId, $modelId);
            } elseif (is_string($preferredModel)) {
                // Model ID
                $modelId = $this->normalizePreferenceIdentifier($preferredModel);
                $preferenceKey = $this->createModelPreferenceKey($modelId);
            } else {
                // Invalid type
                throw new InvalidArgumentException('Model preferences must be model identifiers, instances of ModelInterface, ' . 'or provider/model tuples.');
            }
            $preferenceKeys[] = $preferenceKey;
        }
        $this->modelPreferenceKeys = $preferenceKeys;
        return $this;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/php-ai-client/src/builders/promptbuilder.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-includes/php-ai-client/src/Builders/PromptBuilder.php#L256)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-includes/php-ai-client/src/Builders/PromptBuilder.php#L256-L289)

## 󠀁[Related](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#related)󠁿

| Uses | Description | 
| [PromptBuilder::normalizePreferenceIdentifier()](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/normalizepreferenceidentifier/)`wp-includes/php-ai-client/src/Builders/PromptBuilder.php` |

Normalizes and validates a preference identifier string.

  | 
| [PromptBuilder::createProviderModelPreferenceKey()](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/createprovidermodelpreferencekey/)`wp-includes/php-ai-client/src/Builders/PromptBuilder.php` |

Creates a preference key for a provider/model combination.

  | 
| [PromptBuilder::createModelPreferenceKey()](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/createmodelpreferencekey/)`wp-includes/php-ai-client/src/Builders/PromptBuilder.php` |

Creates a preference key for a model identifier.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wordpress-aiclient-builders-promptbuilder/usingmodelpreference/?output_format=md#changelog)󠁿

| Version | Description | 
| [0.2.0](https://developer.wordpress.org/reference/since/0.2.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwordpress-aiclient-builders-promptbuilder%2Fusingmodelpreference%2F)
before being able to contribute a note or feedback.