Title: GenerativeAiResult
Published: May 20, 2026
Last modified: August 20, 2026

---

# class GenerativeAiResult {}

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#description)
 * [Methods](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#methods)
 * [Source](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#source)
 * [Changelog](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#changelog)

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

Represents the result of a generative AI operation.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#description)󠁿

This DTO contains the generated candidates along with usage statistics and metadata
from the AI provider.

## 󠀁[Methods](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/?output_format=md#methods)󠁿

| Name | Description | 
| [GenerativeAiResult::__clone](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/__clone/) | Performs a deep clone of the result. | 
| [GenerativeAiResult::__construct](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/__construct/) | Constructor. | 
| [GenerativeAiResult::fromArray](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/fromarray/) | {@inheritDoc} | 
| [GenerativeAiResult::getAdditionalData](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getadditionaldata/) | {@inheritDoc} | 
| [GenerativeAiResult::getCandidateCount](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getcandidatecount/) | Gets the total number of candidates. | 
| [GenerativeAiResult::getCandidates](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getcandidates/) | Gets the generated candidates. | 
| [GenerativeAiResult::getId](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getid/) | {@inheritDoc} | 
| [GenerativeAiResult::getJsonSchema](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getjsonschema/) | {@inheritDoc} | 
| [GenerativeAiResult::getModelMetadata](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getmodelmetadata/) | Gets the model metadata. | 
| [GenerativeAiResult::getProviderMetadata](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/getprovidermetadata/) | Gets the provider metadata. | 
| [GenerativeAiResult::getTokenUsage](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/gettokenusage/) | {@inheritDoc} | 
| [GenerativeAiResult::hasMultipleCandidates](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/hasmultiplecandidates/) | Checks if the result has multiple candidates. | 
| [GenerativeAiResult::toArray](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/toarray/) | {@inheritDoc} | 
| [GenerativeAiResult::toAudioFile](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/toaudiofile/) | Converts the first candidate to an audio file. | 
| [GenerativeAiResult::toAudioFiles](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/toaudiofiles/) | Converts all candidates to audio files. | 
| [GenerativeAiResult::toFile](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tofile/) | Converts the first candidate to a file. | 
| [GenerativeAiResult::toFiles](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tofiles/) | Converts all candidates to files. | 
| [GenerativeAiResult::toImageFile](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/toimagefile/) | Converts the first candidate to an image file. | 
| [GenerativeAiResult::toImageFiles](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/toimagefiles/) | Converts all candidates to image files. | 
| [GenerativeAiResult::toMessage](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tomessage/) | Converts the first candidate to a message. | 
| [GenerativeAiResult::toMessages](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tomessages/) | Converts all candidates to messages. | 
| [GenerativeAiResult::toText](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/totext/) | Converts the first candidate to text. | 
| [GenerativeAiResult::toTexts](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/totexts/) | Converts all candidates to text. | 
| [GenerativeAiResult::toVideoFile](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tovideofile/) | Converts the first candidate to a video file. | 
| [GenerativeAiResult::toVideoFiles](https://developer.wordpress.org/reference/classes/wordpress-aiclient-results-dto-generativeairesult/tovideofiles/) | Converts all candidates to video files. |

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

    ```php
    class GenerativeAiResult extends AbstractDataTransferObject implements ResultInterface
    {
        public const KEY_ID = 'id';
        public const KEY_CANDIDATES = 'candidates';
        public const KEY_TOKEN_USAGE = 'tokenUsage';
        public const KEY_PROVIDER_METADATA = 'providerMetadata';
        public const KEY_MODEL_METADATA = 'modelMetadata';
        public const KEY_ADDITIONAL_DATA = 'additionalData';
        /**
         * @var string Unique identifier for this result.
         */
        private string $id;
        /**
         * @var Candidate[] The generated candidates.
         */
        private array $candidates;
        /**
         * @var TokenUsage Token usage statistics.
         */
        private \WordPress\AiClient\Results\DTO\TokenUsage $tokenUsage;
        /**
         * @var ProviderMetadata Provider metadata.
         */
        private ProviderMetadata $providerMetadata;
        /**
         * @var ModelMetadata Model metadata.
         */
        private ModelMetadata $modelMetadata;
        /**
         * @var array<string, mixed> Additional data.
         */
        private array $additionalData;
        /**
         * Constructor.
         *
         * @since 0.1.0
         *
         * @param string $id Unique identifier for this result.
         * @param Candidate[] $candidates The generated candidates.
         * @param TokenUsage $tokenUsage Token usage statistics.
         * @param ProviderMetadata $providerMetadata Provider metadata.
         * @param ModelMetadata $modelMetadata Model metadata.
         * @param array<string, mixed> $additionalData Additional data.
         * @throws InvalidArgumentException If no candidates provided.
         */
        public function __construct(string $id, array $candidates, \WordPress\AiClient\Results\DTO\TokenUsage $tokenUsage, ProviderMetadata $providerMetadata, ModelMetadata $modelMetadata, array $additionalData = [])
        {
            if (empty($candidates)) {
                throw new InvalidArgumentException('At least one candidate must be provided');
            }
            $this->id = $id;
            $this->candidates = $candidates;
            $this->tokenUsage = $tokenUsage;
            $this->providerMetadata = $providerMetadata;
            $this->modelMetadata = $modelMetadata;
            $this->additionalData = $additionalData;
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         */
        public function getId(): string
        {
            return $this->id;
        }
        /**
         * Gets the generated candidates.
         *
         * @since 0.1.0
         *
         * @return Candidate[] The candidates.
         */
        public function getCandidates(): array
        {
            return $this->candidates;
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         */
        public function getTokenUsage(): \WordPress\AiClient\Results\DTO\TokenUsage
        {
            return $this->tokenUsage;
        }
        /**
         * Gets the provider metadata.
         *
         * @since 0.1.0
         *
         * @return ProviderMetadata The provider metadata.
         */
        public function getProviderMetadata(): ProviderMetadata
        {
            return $this->providerMetadata;
        }
        /**
         * Gets the model metadata.
         *
         * @since 0.1.0
         *
         * @return ModelMetadata The model metadata.
         */
        public function getModelMetadata(): ModelMetadata
        {
            return $this->modelMetadata;
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         */
        public function getAdditionalData(): array
        {
            return $this->additionalData;
        }
        /**
         * Gets the total number of candidates.
         *
         * @since 0.1.0
         *
         * @return int The total number of candidates.
         */
        public function getCandidateCount(): int
        {
            return count($this->candidates);
        }
        /**
         * Checks if the result has multiple candidates.
         *
         * @since 0.1.0
         *
         * @return bool True if there are multiple candidates, false otherwise.
         */
        public function hasMultipleCandidates(): bool
        {
            return $this->getCandidateCount() > 1;
        }
        /**
         * Converts the first candidate to text.
         *
         * Only text from the content channel is considered. Text within model thought or reasoning is ignored.
         *
         * @since 0.1.0
         *
         * @return string The text content.
         * @throws RuntimeException If no text content.
         */
        public function toText(): string
        {
            $message = $this->candidates[0]->getMessage();
            foreach ($message->getParts() as $part) {
                $channel = $part->getChannel();
                $text = $part->getText();
                if ($channel->isContent() && $text !== null) {
                    return $text;
                }
            }
            throw new RuntimeException('No text content found in first candidate');
        }
        /**
         * Converts the first candidate to a file.
         *
         * Only files from the content channel are considered. Files within model thought or reasoning are ignored.
         *
         * @since 0.1.0
         *
         * @return File The file.
         * @throws RuntimeException If no file content.
         */
        public function toFile(): File
        {
            $message = $this->candidates[0]->getMessage();
            foreach ($message->getParts() as $part) {
                $channel = $part->getChannel();
                $file = $part->getFile();
                if ($channel->isContent() && $file !== null) {
                    return $file;
                }
            }
            throw new RuntimeException('No file content found in first candidate');
        }
        /**
         * Converts the first candidate to an image file.
         *
         * @since 0.1.0
         *
         * @return File The image file.
         * @throws RuntimeException If no image content.
         */
        public function toImageFile(): File
        {
            $file = $this->toFile();
            if (!$file->isImage()) {
                throw new RuntimeException(sprintf('File is not an image. MIME type: %s', $file->getMimeType()));
            }
            return $file;
        }
        /**
         * Converts the first candidate to an audio file.
         *
         * @since 0.1.0
         *
         * @return File The audio file.
         * @throws RuntimeException If no audio content.
         */
        public function toAudioFile(): File
        {
            $file = $this->toFile();
            if (!$file->isAudio()) {
                throw new RuntimeException(sprintf('File is not an audio file. MIME type: %s', $file->getMimeType()));
            }
            return $file;
        }
        /**
         * Converts the first candidate to a video file.
         *
         * @since 0.1.0
         *
         * @return File The video file.
         * @throws RuntimeException If no video content.
         */
        public function toVideoFile(): File
        {
            $file = $this->toFile();
            if (!$file->isVideo()) {
                throw new RuntimeException(sprintf('File is not a video file. MIME type: %s', $file->getMimeType()));
            }
            return $file;
        }
        /**
         * Converts the first candidate to a message.
         *
         * @since 0.1.0
         *
         * @return Message The message.
         */
        public function toMessage(): Message
        {
            return $this->candidates[0]->getMessage();
        }
        /**
         * Converts all candidates to text.
         *
         * @since 0.1.0
         *
         * @return list<string> Array of text content.
         */
        public function toTexts(): array
        {
            $texts = [];
            foreach ($this->candidates as $candidate) {
                $message = $candidate->getMessage();
                foreach ($message->getParts() as $part) {
                    $channel = $part->getChannel();
                    $text = $part->getText();
                    if ($channel->isContent() && $text !== null) {
                        $texts[] = $text;
                        break;
                    }
                }
            }
            return $texts;
        }
        /**
         * Converts all candidates to files.
         *
         * @since 0.1.0
         *
         * @return list<File> Array of files.
         */
        public function toFiles(): array
        {
            $files = [];
            foreach ($this->candidates as $candidate) {
                $message = $candidate->getMessage();
                foreach ($message->getParts() as $part) {
                    $channel = $part->getChannel();
                    $file = $part->getFile();
                    if ($channel->isContent() && $file !== null) {
                        $files[] = $file;
                        break;
                    }
                }
            }
            return $files;
        }
        /**
         * Converts all candidates to image files.
         *
         * @since 0.1.0
         *
         * @return list<File> Array of image files.
         */
        public function toImageFiles(): array
        {
            return array_values(array_filter($this->toFiles(), fn(File $file) => $file->isImage()));
        }
        /**
         * Converts all candidates to audio files.
         *
         * @since 0.1.0
         *
         * @return list<File> Array of audio files.
         */
        public function toAudioFiles(): array
        {
            return array_values(array_filter($this->toFiles(), fn(File $file) => $file->isAudio()));
        }
        /**
         * Converts all candidates to video files.
         *
         * @since 0.1.0
         *
         * @return list<File> Array of video files.
         */
        public function toVideoFiles(): array
        {
            return array_values(array_filter($this->toFiles(), fn(File $file) => $file->isVideo()));
        }
        /**
         * Converts all candidates to messages.
         *
         * @since 0.1.0
         *
         * @return list<Message> Array of messages.
         */
        public function toMessages(): array
        {
            return array_values(array_map(fn(\WordPress\AiClient\Results\DTO\Candidate $candidate) => $candidate->getMessage(), $this->candidates));
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         */
        public static function getJsonSchema(): array
        {
            return ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'Unique identifier for this result.'], self::KEY_CANDIDATES => ['type' => 'array', 'items' => \WordPress\AiClient\Results\DTO\Candidate::getJsonSchema(), 'minItems' => 1, 'description' => 'The generated candidates.'], self::KEY_TOKEN_USAGE => \WordPress\AiClient\Results\DTO\TokenUsage::getJsonSchema(), self::KEY_PROVIDER_METADATA => ProviderMetadata::getJsonSchema(), self::KEY_MODEL_METADATA => ModelMetadata::getJsonSchema(), self::KEY_ADDITIONAL_DATA => ['type' => 'object', 'additionalProperties' => \true, 'description' => 'Additional data included in the API response.']], 'required' => [self::KEY_ID, self::KEY_CANDIDATES, self::KEY_TOKEN_USAGE, self::KEY_PROVIDER_METADATA, self::KEY_MODEL_METADATA]];
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         *
         * @return GenerativeAiResultArrayShape
         */
        public function toArray(): array
        {
            return [self::KEY_ID => $this->id, self::KEY_CANDIDATES => array_map(fn(\WordPress\AiClient\Results\DTO\Candidate $candidate) => $candidate->toArray(), $this->candidates), self::KEY_TOKEN_USAGE => $this->tokenUsage->toArray(), self::KEY_PROVIDER_METADATA => $this->providerMetadata->toArray(), self::KEY_MODEL_METADATA => $this->modelMetadata->toArray(), self::KEY_ADDITIONAL_DATA => $this->additionalData];
        }
        /**
         * {@inheritDoc}
         *
         * @since 0.1.0
         */
        public static function fromArray(array $array): self
        {
            static::validateFromArrayData($array, [self::KEY_ID, self::KEY_CANDIDATES, self::KEY_TOKEN_USAGE, self::KEY_PROVIDER_METADATA, self::KEY_MODEL_METADATA]);
            $candidates = array_map(fn(array $candidateData) => \WordPress\AiClient\Results\DTO\Candidate::fromArray($candidateData), $array[self::KEY_CANDIDATES]);
            return new self($array[self::KEY_ID], $candidates, \WordPress\AiClient\Results\DTO\TokenUsage::fromArray($array[self::KEY_TOKEN_USAGE]), ProviderMetadata::fromArray($array[self::KEY_PROVIDER_METADATA]), ModelMetadata::fromArray($array[self::KEY_MODEL_METADATA]), $array[self::KEY_ADDITIONAL_DATA] ?? []);
        }
        /**
         * Performs a deep clone of the result.
         *
         * This method ensures that all nested objects (candidates, token usage, metadata)
         * are cloned to prevent modifications to the cloned result from affecting the original.
         *
         * @since 0.4.2
         */
        public function __clone()
        {
            $clonedCandidates = [];
            foreach ($this->candidates as $candidate) {
                $clonedCandidates[] = clone $candidate;
            }
            $this->candidates = $clonedCandidates;
            $this->tokenUsage = clone $this->tokenUsage;
            $this->providerMetadata = clone $this->providerMetadata;
            $this->modelMetadata = clone $this->modelMetadata;
        }
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/php-ai-client/src/results/dto/generativeairesult.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/php-ai-client/src/Results/DTO/GenerativeAiResult.php#L38)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/php-ai-client/src/Results/DTO/GenerativeAiResult.php#L38-L420)

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

| Version | Description | 
| [0.1.0](https://developer.wordpress.org/reference/since/0.1.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-results-dto-generativeairesult%2F)
before being able to contribute a note or feedback.