Integração de IA no WordPress: uma análise detalhada da arquitetura e de um caso de uso real

Antes do WordPress 7.0, os plugins que adicionavam recursos de IA precisavam solicitar e gerenciar uma chave de API para se comunicar com um provedor de IA.

Isso trazia várias desvantagens em termos de tamanho do código e facilidade de manutenção. Era necessário incluir bibliotecas proprietárias de SDK pesadas nos plugins e escrever solicitações cURL específicas para cada provedor.

Esse cenário fragmentado mudou completamente com a integração nativa de IA introduzida no WordPress 7.0. Agora, o WordPress conta com uma interface centralizada para configurar credenciais de diversos provedores de IA, além de uma nova API em PHP. Essa nova arquitetura permite enviar comandos, instruções, arquivos de mídia e estruturas de dados de forma transparente, enquanto o Core gerencia as solicitações.

A nova arquitetura oferece benefícios significativos tanto para administradores de sites quanto para desenvolvedores de plugins.

Os administradores não precisam mais configurar definições de IA em vários plugins. A partir do WordPress 7.0, basta instalar e ativar os conectores do plugin, inserir as chaves de API na interface unificada Connectors, e elas ficarão imediatamente disponíveis para todos os plugins com recursos de IA do site. Também é possível monitorar facilmente o uso da IA, alterar o modelo preferido ou revogar o acesso de um provedor para todos os plugins com apenas um clique.

Para desenvolvedores de plugins, as vantagens são ainda maiores, abrangendo desde segurança de dados até portabilidade de código e uma redução drástica da dívida técnica.

Pronto para conhecer a nova arquitetura de IA do WordPress? Vamos começar.

As três camadas da arquitetura de IA do WordPress

Hoje, seus sites WordPress já estão preparados nativamente para IA. Isso não significa que o WordPress ofereça recursos de IA prontos para uso, mas sim que fornece a base necessária para criar sites com funcionalidades baseadas em IA.

A nova arquitetura é estruturada em três camadas distintas:

AI Connector

Antes do WordPress 7.0, todo plugin que adicionava recursos de IA ao site precisava do próprio sistema para armazenar e gerenciar suas chaves API. As credenciais precisavam ser incorporadas diretamente ao plugin ou gerenciadas por meio de uma página de configurações personalizada. Em ambos os casos, essa estava longe de ser uma solução ideal para lidar com dados sensíveis.

Uma interface unificada permite configurar todos os provedores de serviços de IA em um único local centralizado. Essa interface oferece vários benefícios importantes para o gerenciamento do site.

Do ponto de vista da administração e da segurança, a maior vantagem é que basta configurar os provedores uma única vez na interface Connectors e depois esquecer essa etapa, independentemente da quantidade de plugins que os utilizam. Se precisar alterar as chaves de API no futuro, não será necessário reconfigurar cada plugin individualmente; basta atualizá-las uma única vez na tela Connectors.

Centralizar as credenciais também melhora a segurança do site ao reduzir o risco de exposição de dados sensíveis por meio de plugins de terceiros que possam ter sido mal desenvolvidos ou não sejam confiáveis.

Outra vantagem importante é a portabilidade do código. Os plugins não precisam mais saber qual provedor de IA está sendo utilizado, pois a nova arquitetura desacopla a autenticação da lógica do plugin. Isso significa que, se você mudar de provedor de IA, o plugin continuará funcionando sem exigir uma única alteração no código.

No entanto, o maior avanço em termos de portabilidade é a possibilidade de os administradores configurarem vários conectores simultaneamente. Quando um plugin envia uma solicitação, o WordPress seleciona automaticamente o provedor de IA e o modelo mais adequados para gerar a resposta, com base tanto na configuração específica do plugin quanto nos recursos dos modelos disponíveis.

AI Client

Enquanto a tela Connectors fornece a interface de configuração dos provedores de IA, o AI Client oferece aos desenvolvedores a ferramenta operacional para se comunicar com os modelos de IA.

Trata-se de uma interface de software nativa que padroniza a interação com modelos de inteligência artificial por meio da função global wp_ai_client_prompt() e de um conjunto unificado de métodos em PHP.

Redução da dívida técnica

Para os desenvolvedores, uma das principais vantagens da nova arquitetura de IA é a redução da dívida técnica e das dependências. Antes do WordPress 7.0, adicionar recursos de IA implicava um custo muito alto em termos de manutenção do código. Era necessário incluir SDKs proprietários de terceiros (como as bibliotecas oficiais da OpenAI ou da Anthropic) e monitorar constantemente suas versões. Isso tornava a base de código do plugin mais pesada e aumentava a possibilidade de erros de compatibilidade.

Além disso, era preciso escrever muitas linhas de código para lidar com a lógica de rede e o processamento das respostas. Para piorar, esse código era específico para cada fornecedor. Assim, se você decidisse mudar de provedor de IA, precisaria reescrever toda a arquitetura de comunicação do plugin.

O AI Client resolve esse problema na origem ao transferir todo esse trabalho para o Core do WordPress. O código torna-se completamente independente do provedor de IA: basta escrever as instruções uma única vez, e o WordPress as traduzirá para o “dialeto” específico do modelo utilizado.

Seleção inteligente de modelos

Um recurso poderoso da Fluent Interface do AI Client é a possibilidade de definir modelos preferenciais por meio do método using_model_preference(), disponível na função construtora wp_ai_client_prompt(). Esse método permite declarar uma lista ordenada de modelos para a tarefa específica do plugin. Por exemplo, o código abaixo solicita a geração de texto priorizando três modelos:

$text_result = wp_ai_client_prompt( 'Convert the following transcript into a concise, blog-ready draft.' )
	->using_model_preference(
		'gemini-2.5-flash',
		'claude-3-5-sonnet',
		'gpt-4o'
	)
	->generate_text();

O WordPress verificará os provedores configurados na tela Connectors e comparará a lista de modelos definida no código do plugin, selecionando o primeiro conector que também esteja disponível no site. Se nenhum dos modelos especificados no código estiver disponível entre os Connectors ativos, o WordPress ignorará a lista de preferência e utilizará o primeiro modelo compatível configurado no site.

Esse mecanismo garante que o plugin continuará funcionando mesmo que o administrador do site decida mudar para outro provedor de IA.

Provedor de IA

Um provedor de IA é a empresa que possui, treina e hospeda os Grandes Modelos de Linguagem (LLMs) que usamos todo dia. OpenAI, Google Gemini e Anthropic são os provedores de IA mais comuns suportados por meio de conectores dedicados no WordPress 7.0, mas os desenvolvedores podem registrar provedores de IA personalizados adicionais.

Quando o código do plugin chama o método generate_text(), ou qualquer outro método de geração, o WordPress compila e envia uma carga de dados (payload) para o provedor de IA por meio do endpoint definido pelo Connector. Nos bastidores, a sequência de operações ocorre da seguinte forma:

• Primeiro, o provedor de IA recebe o texto do prompt de entrada juntamente com todos os arquivos de mídia anexados (carga de dados).
• Em seguida, processa a solicitação, aplicando as instruções do sistema, quando houver.
• Depois, gera a resposta estruturada como texto livre ou como um objeto JSON.
• Por fim, envia o resultado de volta ao WordPress por meio de uma resposta HTTP.

Cada provedor oferece uma ampla variedade de modelos com diferentes capacidades, velocidades e custos. Há modelos especializados exclusivamente em processamento de texto, modelos multimodais que aceitam arquivos de mídia (áudio, imagens e vídeos) juntamente com um prompt de texto e modelos desenvolvidos para tarefas específicas, como geração de imagens ou conversão de fala em texto.

Novamente, os modelos disponíveis para um site WordPress dependem dos provedores de IA configurados pelo usuário na tela Connectors. Isso significa que o plugin não determina qual provedor específico será utilizado.

Uma análise detalhada da função wp_ai_client_prompt()

A função wp_ai_client_prompt() permite que os plugins se comuniquem com modelos de IA de forma padronizada. Assim, você não precisa instalar bibliotecas externas, lidar com configurações específicas de cada provedor nem implementar manualmente solicitações HTTP.

Ela funciona como uma interface de software que permite escrever o código apenas uma vez, enquanto o WordPress faz todo o trabalho pesado e traduz as instruções para o “dialeto” específico de cada modelo.

A função retorna uma instância da classe WP_AI_Client_Prompt_Builder, que fornece uma interface fluente (Fluent Interface) composta por métodos encadeáveis para personalizar os prompts. A função é descrita da seguinte forma:

/**
 * Fluent builder for constructing AI prompts, returning WP_Error on failure.
 *
 * This class provides a fluent interface for building prompts with various
 * content types and model configurations. It wraps the PHP AI Client SDK's
 * PromptBuilder and adds WordPress-specific behavior including WP_Error
 * handling instead of exceptions, snake_case method naming, and integration
 * with the Abilities API.
 *
 * Only the generating methods will return a WP_Error, to not break the fluent
 * interface. As soon as any exception is caught in a chain of method calls,
 * the returned instance will be in an error state, and all subsequent method
 * calls will be no-ops that just return the same error state instance. Only
 * when a generating method is called, the WP_Error will be returned.
 */

A função wp_ai_client_prompt() não faz uma solicitação HTTP imediatamente. Em vez disso, ela instancia e retorna um objeto WP_AI_Client_Prompt_Builder. Mais de 50 métodos de configuração preenchem as propriedades privadas desse objeto por meio de uma Fluent Interface, tornando o código altamente legível e fácil de escrever.

Veja uma lista não exaustiva dos métodos que você utilizará com mais frequência:

• with_text(): adiciona texto à mensagem atual.
• with_file(): adiciona um arquivo à mensagem atual.
• with_history(): adiciona o histórico da conversa.
• using_model_preference(): define os modelos preferenciais em ordem de prioridade.
• using_system_instruction(): define a instrução do sistema.
• using_max_tokens(): define o número máximo de tokens a serem gerados.
• using_temperature(): define a temperatura da geração.
• using_top_p(): define o valor de top-p da geração.
• using_top_k(): define o valor de top-k da geração.
• as_output_file_type(): define o tipo do arquivo de saída.
• as_json_response(): configura o prompt para retornar uma resposta em JSON.
• is_supported_for_text_generation(): verifica se a configuração ativa oferece suporte à geração de texto.
• is_supported_for_image_generation(): verifica se a configuração ativa oferece suporte à geração de imagens.
• is_supported_for_text_to_speech_conversion(): verifica se a configuração ativa oferece suporte à conversão de texto em fala.
• is_supported_for_video_generation(): verifica se a configuração ativa oferece suporte à geração de vídeos.
• generate_text(): gera um resultado em texto a partir do prompt.
• generate_image(): gera uma imagem a partir do prompt.
• convert_text_to_speech(): converte texto em fala.
• generate_speech(): gera fala a partir do prompt.
• generate_video(): gera um vídeo a partir do prompt.

Para obter a lista completa de métodos, consulte o código-fonte do Core do WordPress.

Suponha que você queira transcrever com precisão o conteúdo de um arquivo de áudio. Nesse caso, você pode utilizar a função da seguinte forma:

$transcription_builder = wp_ai_client_prompt( $prompt )
	->with_file( $audio_base64, $mime_type )
	->using_temperature( 0.1 );

if ( ! $transcription_builder->is_supported_for_text_generation() ) {
	// No configured provider supports the current prompt configuration.
	return new WP_Error(
		'no_supported_model',
		'No configured AI model can process this request. Configure a provider in Settings > Connectors.',
		array( 'status' => 400 )
	);
}

$transcript = $transcription_builder->generate_text();

Veja o que esse código faz:

• $prompt: representa a string principal que contém as instruções centrais.
• with_file(): habilita os recursos multimodais da interface. No exemplo acima, passamos o conteúdo binário do áudio previamente codificado em Base64 juntamente com o respectivo tipo MIME.
• using_temperature(): controla o grau de determinismo da resposta. Um valor baixo (0,1) faz com que o modelo permaneça o mais fiel possível ao conteúdo do áudio, enquanto um valor mais alto permite maior liberdade criativa. Esse método pode ser combinado com using_top_p() (Top-Probability) para um controle ainda mais preciso do resultado.
• is_supported_for_text_generation(): verifica se os Connectors ativos oferecem suporte aos requisitos do prompt atual antes de consumir recursos com uma chamada de rede.
• generate_text(): é o método final da Fluent Interface. Ele envia a solicitação HTTP unificada ao provedor ativo e retorna o texto gerado ou um objeto WP_Error em caso de falha.

Em resumo, enviamos ao provedor de IA um prompt de texto acompanhado de um arquivo de áudio. Definimos uma temperatura baixa para obter o resultado mais determinístico possível, verificamos se a configuração ativa era compatível com a geração de texto e, por fim, executamos a transcrição de fala para texto com base na resposta da IA.

Com outro prompt, podemos enviar novamente a transcrição bruta para a IA e solicitar que ela gere uma resposta estruturada como um objeto JSON.

$structured_json = wp_ai_client_prompt(
	"Convert the following transcript into a concise, blog-ready draft in American English.n" .
	"Return JSON with a post title and body sections.n" .
	"Each section must have: heading, level (2 or 3), and paragraphs (array).n" .
	"If useful, include bullet_points (array) for short actionable lists.n" .
	"Use short, clear headings and readable paragraph text.nn" .
	"Transcript:n" . $transcript
)
	->using_system_instruction( "You are a professional WordPress content editor. Always write in American English (use appropriate spelling, grammar, and conventions for that language variant)." )
	->using_temperature( 0.4 )
	->as_json_response( $schema )
	->generate_text();

Para esse segundo prompt, utilizamos métodos adicionais para aproveitar outros recursos da API:

• using_system_instruction(): define o contexto operacional e o papel comportamental do modelo, separando claramente sua persona (“um editor profissional de conteúdo do WordPress”) da carga de dados.
• using_temperature( 0.4 ): define uma “temperatura” mais alta do que na tarefa de transcrição anterior, permitindo que o modelo use um vocabulário mais rico e produza um conteúdo mais fluido.
• as_json_response(): obriga o modelo a retornar uma string JSON estruturada que corresponda ao layout definido na sua variável $schema. Isso é útil ao preparar conteúdo para o Gutenberg.

Com a saída estruturada como JSON, você pode extrair campos individuais e mapeá-los programaticamente para blocos nativos do Gutenberg utilizando as funções do Core do WordPress.

Para uma visão mais aprofundada do AI Client, consulte também a nota de desenvolvimento Introducing the AI Client in WordPress 7.0.

Converta um arquivo de áudio em conteúdo pronto para o Gutenberg com IA

Agora que você entende melhor as três camadas da arquitetura de IA do WordPress, vamos ver como tudo isso funciona na prática com um exemplo real. Nesta seção, você aprenderá a criar a lógica principal de um plugin baseado em IA capaz de gerar um rascunho de artigo bem estruturado diretamente a partir de um arquivo de áudio.

Os casos de uso para esse recurso são inúmeros. Imagine criar um artigo completo para um blog a partir de uma rápida mensagem de voz enviada pelo seu aplicativo de mensagens favorito ou transcrever uma entrevista gravada no smartphone.

Para implementar essa funcionalidade no seu site WordPress, será necessário criar um plugin personalizado. Não abordaremos aqui os arquivos básicos (boilerplate) nem todo o processo de registro do plugin. Se precisar revisar os fundamentos do desenvolvimento de plugins, consulte outros tutoriais do blog da Kinsta ou a documentação oficial do WordPress.org.

Nos concentraremos na lógica principal que permite ao plugin se comunicar com o provedor de IA. Mas não se preocupe: o plugin está disponível para consulta e download neste repositório do GitHub.

O que este plugin faz

Para começar, acesse a página do projeto no GitHub e baixe o arquivo ZIP do plugin. Em seguida, faça login no painel do WordPress 7.0 ou superior e envie o arquivo em Plugins > Adicionar plugin > Enviar plugin. Após instalar e ativar o plugin, você estará pronto para acompanhar este tutorial.

O plugin AI Content Builder adiciona uma barra lateral de configurações personalizada, acessível por meio de um ícone localizado no canto superior direito da interface do Editor de Blocos. Essa barra lateral inclui uma interface dedicada para o envio de arquivos de áudio e um botão de alternância que permite à IA substituir o título atual do artigo.

O botão Upload audio note abre o carregador de mídia do WordPress, permitindo enviar um novo arquivo de áudio ou selecionar um arquivo existente da Biblioteca de Mídia.

Depois que o arquivo de áudio é carregado, o botão Generate Content dispara uma solicitação assíncrona para o provedor de IA ativo.

A imagem abaixo mostra o rascunho final do post gerado pela IA em apenas alguns segundos.

O conteúdo resultante é estruturado em blocos nativos do Gutenberg, incluindo parágrafos, títulos e listas.

Agora, vamos analisar a lógica do plugin.

O que você precisa para este plugin

Estes são os requisitos básicos para criar um plugin WordPress que se integre à nova arquitetura de IA para gerar o conteúdo dos seus posts:

• WordPress 7.0 ou superior.
• Uma chave de API de um provedor de IA que ofereça um modelo capaz de realizar conversão de fala em texto. Em nosso exemplo, usaremos o Google AI.
• Seu IDE preferido. Para este plugin, usamos o VS Code.
• Conhecimento sólido sobre desenvolvimento para WordPress e Gutenberg, APIs REST, PHP e JavaScript.

Você não precisa se preocupar com Node.js, processos de build ou importação de bibliotecas externas, pois este plugin utiliza exclusivamente as APIs nativas do Core do WordPress. O resultado é um plugin leve, seguro e sem dívida técnica.

Estrutura do plugin e versão mínima do WordPress

O plugin AI Content Builder é composto por apenas dois arquivos:

• ai-content-builder.php
• editor.js.

A versão mínima necessária do WordPress é a 7.0. Portanto, certifique-se de defini-la no cabeçalho do plugin:

<?php
/**
 * Plugin Name: AI Content Builder
 * Description: Gutenberg sidebar plugin that uploads audio and generates post content using the WordPress 7.0 AI Client.
 * Version: 1.0.0
 * Requires at least: 7.0
 * Requires PHP: 8.0
 * Author: Your Name
 * License: GPL-2.0-or-later
 * Text Domain: ai-content-builder
 */

Com isso em mente, vamos analisar o processo de criação de um plugin para WordPress com recursos de IA.

O fluxo de dados do plugin

Antes de analisarmos o código, vamos entender como os dados percorrem o caminho entre o backend do WordPress, o Editor de Blocos, o servidor PHP e o provedor de IA, e depois retornam ao editor.

1. Do navegador para o servidor: chamada REST assíncrona: o navegador envia o ID do arquivo de áudio para o endpoint REST personalizado do plugin. Para evitar que a interface fique travada, registramos um endpoint REST que permite enviar solicitações assíncronas ao servidor PHP.
2. Primeira etapa de IA: transcrição de fala em texto: o servidor intercepta a solicitação, recupera o arquivo de áudio do banco de dados e consulta o AI Client para extrair a transcrição bruta.
3. Segunda etapa de IA: estruturação do conteúdo: o servidor envia a transcrição bruta novamente ao AI Client e solicita que ela seja formatada como um objeto JSON estruturado.
4. Preenchimento dos dados e geração dos blocos: o script JavaScript (JS) recebe o objeto JSON estruturado, normaliza os dados e mapeia os campos para blocos nativos do Gutenberg.

Agora, vamos analisar a lógica por trás de cada etapa.

1. Registrar um endpoint de API personalizado

O primeiro passo para criar o plugin AI Content Builder é registrar um endpoint de API. Isso é essencial porque processar um arquivo de áudio e gerar uma resposta pode levar vários segundos (ou até minutos) para o modelo de IA. Registrar um endpoint REST permite que você faça solicitações assíncronas pelos controles da barra lateral, evitando que a interface congele.

Registrar um endpoint de API também permite fazer chamadas seguras à IA sem expor credenciais de acesso, aproveitando o sistema nativo de autenticação do WordPress.

A lógica para registrar e inicializar o endpoint é tratada no arquivo PHP do plugin usando os dois métodos de classe: init() e register_rest_routes().

public static function init(): void {

	// Register the custom REST endpoint used by the sidebar JS.
	add_action( 'rest_api_init', array( __CLASS__, 'register_rest_routes' ) );

	...
}

Ao vincular a chamada da função ao hook rest_api_init, o plugin registra a rota do endpoint somente quando uma solicitação à API REST é acionada. Isso melhora o desempenho ao evitar atrasos desnecessários no carregamento das páginas.

Você pode configurar as rotas usando o método register_rest_routes(), conforme mostrado no código abaixo:

public static function register_rest_routes(): void {
	register_rest_route(
		self::REST_NAMESPACE,
		self::REST_ROUTE,
		array(
			'methods'             => WP_REST_Server::CREATABLE, // Alias for POST.
			'callback'            => array( __CLASS__, 'handle_generate_request' ),
			'permission_callback' => static function (): bool {
				// Reject unauthenticated or insufficiently privileged requests early.
				return current_user_can( 'edit_posts' );
			},
			'args'                => array(
				'audio_id' => array(
					'type'     => 'integer',
					'required' => true,
				),
			),
		)
	);
}

Esse método faz o seguinte:

• A função register_rest_route() recebe três parâmetros: o namespace da rota, a própria rota e um array de configuração.
• WP_REST_Server::CREATABLE é um alias do método de transporte POST, utilizado para garantir a máxima compatibilidade com a arquitetura interna do WordPress.
• permission_callback é é uma função anônima que restringe o acesso a usuários autenticados com permissão para criar e editar os próprios posts. Em caso de acesso não autorizado, o WordPress bloqueia a solicitação antes de processá-la e retorna automaticamente um erro 401 Unauthorized ou 403 Forbidden.
• args é um array opcional de parâmetros adicionais que podem ser utilizados para modificar a resposta da API. Ele permite especificar os dados que a solicitação ao endpoint deve retornar.
• audio_id é um array de parâmetros que especifica o tipo de dado obrigatório. Se o tipo retornado não for um número inteiro ou se o valor estiver ausente, a API REST interromperá a execução e retornará um erro.

Por fim, é necessário garantir que a barra lateral do editor saiba para onde enviar os dados. Para isso, usamos a função wp_localize_script() dentro do método enqueue_editor_assets().

public static function enqueue_editor_assets(): void {
	...

	wp_localize_script(
		'ai-content-builder-editor',
		'AICBData',
		array(
			'restPath' => '/' . self::REST_NAMESPACE . self::REST_ROUTE,
			'nonce'    => wp_create_nonce( 'wp_rest' ),
		)
	);
}

• A função wp_localize_script() é utilizada principalmente para disponibilizar dados de localização de um script registrado por meio de uma variável JavaScript. No entanto, aqui ela é usada para transferir dados do PHP para o JavaScript por meio do objeto global AICBData.
• restPath contém o endereço do endpoint. Defini-lo aqui evita que ele precise ser inserido diretamente no arquivo JavaScript.
• nonce define um token de segurança para impedir acessos não autorizados.

2. Acessar o AI Client para extrair texto de um arquivo de áudio

O método handle_generate_request() é o núcleo do nosso plugin. Ele executa uma sequência de tarefas, começando pelas verificações de segurança e terminando com a geração do conteúdo do post que será inserido no Editor de Blocos.

Primeiro, ele verifica se o AI Client está disponível e se o suporte à IA não foi desativado no site.

public static function handle_generate_request( WP_REST_Request $request ) {
	if ( ! function_exists( 'wp_ai_client_prompt' ) ) {
		return new WP_Error(
			'ai_client_unavailable',
			'WordPress AI Client is not available. This plugin requires WordPress 7.0 .',
			array( 'status' => 500 )
		);
	}

	if ( function_exists( 'wp_supports_ai' ) && ! wp_supports_ai() ) {
		return new WP_Error(
			'ai_disabled',
			'AI support is disabled on this site.',
			array( 'status' => 403 )
		);
	}
	...
}

Em caso de falha, essas verificações retornam um erro 500 ou 403, respectivamente.

O próximo bloco de código executa as seguintes ações:

• Extrai o ID do arquivo de áudio da solicitação.
• Verifica se o ID do arquivo de áudio é um número inteiro positivo.
• Verifica o tipo do arquivo.
• Recupera o tipo MIME.
• Extrai e codifica o conteúdo do arquivo em Base64.

$audio_id = absint( $request->get_param( 'audio_id' ) );
if ( ! $audio_id ) {
	return new WP_Error( 'invalid_audio_id', 'Invalid audio ID.', array( 'status' => 400 ) );
}

$attachment = get_post( $audio_id );
if ( ! $attachment || 'attachment' !== $attachment->post_type ) {
	return new WP_Error( 'audio_not_found', 'Audio attachment not found.', array( 'status' => 404 ) );
}

$mime_type = (string) get_post_mime_type( $audio_id );
if ( 0 !== strpos( $mime_type, 'audio/' ) ) {
	return new WP_Error( 'invalid_audio_type', 'Attachment must be an audio file.', array( 'status' => 400 ) );
}

$audio_path = get_attached_file( $audio_id );
if ( ! $audio_path || ! file_exists( $audio_path ) ) {
	return new WP_Error( 'audio_path_missing', 'Audio file path not found on server.', array( 'status' => 404 ) );
}

$audio_bytes = file_get_contents( $audio_path );
if ( false === $audio_bytes ) {
	return new WP_Error( 'audio_read_failed', 'Unable to read audio file.', array( 'status' => 500 ) );
}

$audio_base64 = base64_encode( $audio_bytes );

Dessa forma, o arquivo binário é convertido em uma string que pode ser enviada ao AI Client. Agora, podemos prosseguir com a extração do texto:

$output_language = self::get_output_language();

$transcription_builder = wp_ai_client_prompt(
	"Transcribe this voice note accurately into $output_language. Return plain text only."
)
	->with_file( $audio_base64, $mime_type )
	->using_temperature( 0.1 );

if ( ! $transcription_builder->is_supported_for_text_generation() ) {
	return new WP_Error(
		'no_supported_model',
		'No configured AI model can process this request. Configure a provider in Settings > Connectors.',
		array( 'status' => 400 )
	);
}

$transcript = $transcription_builder->generate_text();

Veja em detalhes o que o código acima faz:

• get_output_language() é um método estático definido em outra parte do script que retorna a localidade do site. Consulte o GitHub.
• wp_ai_client_prompt() inicializa uma nova solicitação ao receber o prompt principal.
• with_file() informa ao AI Client que estamos enviando uma solicitação multimodal. O método recebe o conteúdo do arquivo em Base64 e o tipo MIME.
• using_temperature() permite especificar o nível de determinismo da resposta. Definimos um valor baixo para obter uma transcrição fiel do áudio.
• O método is_supported_for_text_generation() verifica se o provedor de IA pode gerar texto a partir dos dados fornecidos. Caso o provedor não ofereça suporte a entradas multimodais, o plugin interrompe a execução e retorna uma mensagem de erro.
• O método generate_text() inicia a solicitação HTTP.

3. Converter a transcrição do áudio em conteúdo estruturado

Agora que temos a transcrição, o plugin precisa se comunicar novamente com o provedor de IA para obter uma resposta JSON estruturada. Para isso, precisamos definir um array estruturado no formato JSON.

$schema = array(
	'type'       => 'object',
	'properties' => array(
		'title'    => array( 'type' => 'string' ),
		'sections' => array(
			'type'  => 'array',
			'items' => array(
				'type'       => 'object',
				'properties' => array(
					'heading'    => array( 'type' => 'string' ),
					'level'      => array(
						'type' => 'integer',
					),
					'paragraphs' => array(
						'type'  => 'array',
						'items' => array( 'type' => 'string' ),
					),
					'bullet_points' => array(
						'type'  => 'array',
						'items' => array( 'type' => 'string' ),
					),
				),
				'required'   => array( 'heading', 'level', 'paragraphs' ),
			),
		),
	),
	'required'   => array( 'title', 'sections' ),
);

Com essa estrutura, a IA responderá com um objeto JSON contendo um título e um array de seções. Cada seção deve conter um título, um nível de título, pelo menos um parágrafo e marcadores.

Agora que o esquema foi definido, podemos prosseguir com a configuração da segunda solicitação ao AI Client:

$structured_json = wp_ai_client_prompt(
	"Convert the following transcript into a concise, blog-ready draft in $output_language.n" .
	"Return JSON with a post title and body sections.n" .
	"Each section must have: heading, level (2 or 3), and paragraphs (array).n" .
	"If useful, include bullet_points (array) for short actionable lists.n" .
	"Use short, clear headings and readable paragraph text.nn" .
	"Transcript:n" . $transcript
)
	->using_system_instruction( "You are a professional WordPress content editor. Always write in $output_language (use appropriate spelling, grammar, and conventions for that language variant)." )
	->using_temperature( 0.4 )
	->as_json_response( $schema )
	->generate_text();

if ( is_wp_error( $structured_json ) ) {
	return $structured_json;
}

Vamos analisar os principais pontos desse código:

• using_system_instruction() define a persona do modelo.
• using_temperature( 0.4 ) define um valor de temperatura mais alto, dando à IA maior liberdade criativa para gerar a resposta e produzir um texto mais fluido e elaborado.
• as_json_response( $schema ) instrui o cliente a fornecer a resposta em um formato estruturado.
• O plugin interrompe a execução em caso de erro.

A próxima etapa é decodificar e higienizar os dados.

$structured = json_decode( (string) $structured_json, true );

if ( ! is_array( $structured ) ) {
	return new WP_Error(
		'invalid_ai_json',
		'Could not parse structured AI response.',
		array( 'status' => 500 )
	);
}

$normalized = self::normalize_structured_post( $structured );

if ( '' === $normalized['title'] && empty( $normalized['sections'] ) ) {
	return new WP_Error(
		'empty_structured_content',
		'The AI provider returned empty structured content.',
		array( 'status' => 500 )
	);
}

No código acima:

• A função json_decode() converte a string JSON em um array associativo do PHP.
• Se o JSON estiver malformado, a verificação seguinte retornará um código de status 500 acompanhado de uma mensagem de erro clara.
• O método estático normalize_structured_post() higieniza e normaliza a saída do provedor antes de disponibilizá-la ao JavaScript. Consulte a definição dessa função no GitHub).

Agora, resta apenas enviar a saída resultante ao JavaScript para gerar blocos nativos do Gutenberg.

4. Gerar uma saída pronta para o Gutenberg

A próxima etapa é mapear a saída JSON para blocos nativos do Gutenberg. Essa fase ocorre no lado do cliente e é gerenciada pelo arquivo editor.js.

Quando o usuário seleciona um arquivo de áudio, o código a seguir é acionado:

function AIContentBuilderSidebar() {

	const [ audioId, setAudioId ] = useState( 0 );
	...

	const onSelectAudio = function ( media ) {
		if ( ! media || ! media.id ) {
			return;
		}
		setAudioId( media.id );
		setAudioLabel( media.title || media.filename || ( 'Audio #'   media.id ) );
		setNotice( null );
	};
	...
}

Esse código recupera do banco de dados do WordPress o ID do arquivo de áudio gravado.

Quando o usuário clica no botão Generate Content, a função onGenerate() utiliza apiFetch() para enviar uma solicitação POST ao endpoint da API, incluindo, entre outros dados, o ID do arquivo de áudio.

const onGenerate = async function () {

	...

	try {
		const response = await apiFetch( {
			path: AICBData.restPath,
			method: 'POST',
			headers: {
				'X-WP-Nonce': AICBData.nonce,
			},
			data: {
				audio_id: audioId,
			},
		} );
		...
	}
	...
}

• await pausa a função temporariamente para evitar que o navegador trave enquanto espera pela resposta da IA.
• Assim que for recebido, o objeto JSON fica armazenado temporariamente na variável response.

O conteúdo da variável response será um objeto estruturado da seguinte forma:

{
	title: "Two Wheels to the Medina: ...",
	sections: [
		{
			heading: "A Well-Deserved Rest in the Red City",
			level: 2,
			paragraphs: [ "On April 24th, our group of seven motorcyclists..." ],
			bullet_points: []
		},
		{
			heading: "Diving into the Medina and Jemaa el-Fnaa",
			level: 2,
			paragraphs: [ "We spent the day exploring the historic Medina..." ],
			bullet_points: [ 
				"Navigating the vibrant, maze-like alleys of the ancient Medina", 
				"Tasting traditional Berber tagines and Moroccan mint tea",
				"Shopping for handmade leather goods, spices, and lanterns in the souks" 
			]
		},
		{...}
	],
	content: "Fallback plain text...",
	transcript: "Full transcript..."
}

Esse objeto fornece os dados necessários para criar os blocos. No entanto, o script pode receber uma string JSON ou um JSON aninhado dentro de um objeto. Portanto, é necessária uma etapa adicional de normalização antes de extrair os dados usados na geração dos blocos:

const normalizedSections = normalizeSectionsPayload( response.sections );

• A função normalizeSectionsPayload() normaliza cargas de dados sections incertas, transformando-as em um array. (Veja o código no GitHub.)

Em seguida, a variável normalizedSections é passada como argumento para a função que converte os campos sections em blocos nativos do Gutenberg:

const structuredBlocks = buildBlocksFromSections( normalizedSections );

Abaixo está um trecho da função buildBlocksFromSections():

function buildBlocksFromSections( sections ) {
	if ( ! Array.isArray( sections ) ) {
		return [];
	}

	const blocks = [];

	sections.forEach( function ( section ) {
		if ( ! section || 'object' !== typeof section ) {
				return;
			}

			const heading =
				( 'string' === typeof section.heading )
					? section.heading.trim()
					: '';

			const level = ( 3 === section.level ) ? 3 : 2;

			if ( heading ) {
				blocks.push(
					createBlock( 'core/heading', {
						content: heading,
						level: level,
					} )
				);
			}

			...

		} );
	return blocks;
}

No código acima, o loop forEach() percorre o array de dados e extrai section.heading e section.level, que são utilizados pela função nativa createBlock().

Para o mapeamento de section.paragraphs e section.bullet_points, dá uma olhada no código-fonte no GitHub.

Possibilidades ilimitadas de expansão

A introdução da IA no WordPress abre possibilidades completamente novas tanto para administradores de sites quanto para desenvolvedores. Antes, era necessário criar toda uma infraestrutura de comunicação do zero apenas para adicionar recursos de IA a um site WordPress. Agora, automatizar o fluxo de trabalho editorial e implementar funcionalidades baseadas em IA tornou-se muito mais simples.

O plugin de exemplo apresentado na segunda parte deste artigo demonstra apenas um caso de uso. Ainda assim, ele mostra claramente como agora é possível criar ferramentas que simplificam de forma significativa o gerenciamento de sites e a edição de conteúdo. Além disso, essa arquitetura viabiliza recursos avançados que antes eram complexos demais para implementar ou tinham um custo elevado.

E isso é apenas o começo. A inteligência artificial é uma realidade em constante evolução que, sem dúvida, desencadeará uma grande onda de inovação.

E por falar em inovação… Você já experimentou a hospedagem da Kinsta? Para equipar seu site com as melhores tecnologias disponíveis atualmente para WordPress, experimente a Kinsta sem riscos ou entre em contato com nossa equipe de vendas para saber mais.