PHP API

The Aimogen Pro PHP API - the aimogen() helper, its methods, the response object, threads and practical examples.

Added in 2.8.3, the PHP API is the supported way to use Aimogen Pro from your own code. It reuses your configured API keys, models, limits, filters, logging and provider settings.

The in-plugin reference lives at Settings › PHP API.

Accessing it#

php
$response = aimogen()->ask( 'Write a short description for a WordPress SEO plugin.' );

if ( $response->ok() ) {
    echo esc_html( $response->text() );
} else {
    echo esc_html( $response->error() );
}

If your code loads before the plugin, use the readiness action:

php
add_action( 'aimogen_api_ready', function ( $api ) {
    $response = $api->ask( 'Write a haiku about WordPress.' );
    if ( $response->ok() ) {
        error_log( $response->text() );
    }
} );

Methods#

ask( $prompt, $args = array() )#

General text generation. Runs as a chat request.

php
$response = aimogen()->ask( 'Summarise this in two sentences: ' . $text, array(
    'model'       => 'gpt-5-mini',
    'max_tokens'  => 300,
    'temperature' => 0.5,
) );

extract( $prompt, $schema = array(), $args = array() )#

Structured extraction. Appends schema instructions, strips markdown fences and decodes the JSON.

php
$response = aimogen()->extract(
    'Extract the product details from: ' . $description,
    array(
        'name'     => 'string',
        'price'    => 'number',
        'features' => array( 'string' ),
    )
);

if ( $response->ok() ) {
    $data = $response->data();
}

A decode failure returns a failed response with the raw text in the metadata, rather than throwing.

see( $prompt, $image_url, $args = array() )#

Vision. Requires a vision-capable model.

php
$response = aimogen()->see(
    'Describe what is in this image, in one sentence.',
    'https://example.com/photo.jpg'
);

paint( $prompt, $args = array() )#

Image generation.

php
$response = aimogen()->paint( 'A minimalist illustration of a coffee bean', array(
    'model'     => 'gpt-image-2',
    'size'      => '1024x1024',
    'number'    => 1,
    'file_name' => 'coffee-bean',
) );

if ( $response->ok() ) {
    echo esc_url( $response->url() );
}

Accepted arguments: number (default 1), size (default 1024x1024), model (default gpt-image-2), file_name, nocopy, env.

thread( $thread_id = '' )#

Lightweight conversation memory. History is stored in a transient for seven days.

php
$thread = aimogen()->thread( 'support-' . get_current_user_id() );

$reply = $thread->say( 'What are your opening hours?' );
echo esc_html( $reply->text() );

$reply = $thread->say( 'And on Sundays?' );   // remembers the previous turn

$thread->forget();  // clear it

say() accepts a history argument capping the retained turns, default 20.

agent( $assistant_id )#

Returns an object bound to an AI Assistant.

run( $prompt, $args = array() )#

The underlying method the others call. Use it when you need an argument the convenience methods do not expose.

Arguments#

Accepted by run(), and therefore by ask(), see() and extract():

ArgumentDefaultMeaning
modelThe configured defaultFalls back to the default if the model is not recognised
max_tokens / tokensComputedCaps the output budget
temperature1
top_p1
presence_penalty0
frequency_penalty0
is_chattrueChat versus completion
envPer methodThe environment label recorded in the usage logs
assistant_idemptyUse an assistant
thread_idemptyAssistants thread
vision_fileemptyImage URL for vision
user_questionemptyThe user question passed alongside
roleuserMessage role
embedding_namespaceemptyRetrieval namespace
function_resultemptyA tool result to feed back
file_dataemptyFile data
parse_markdownfalseConvert markdown to HTML
store_datafalseAsk the provider to retain the request
functionsarray()Forced tool definitions
mcp_serversemptyMCP servers to enable
internetenabledPass false to disable internet access
embeddingsenabledPass false to disable retrieval
streamfalseStreaming

env is worth setting. It appears in System & Logs › Usage Logs, so you can attribute cost to your integration.

The response object#

Every method returns an Aimogen_Response.

MethodReturns
ok()true on success
failed()true on failure
text()The generated text
data()Decoded structured data
url()An image URL, for paint()
raw()The raw value
error()The error message
meta( $key = null )Metadata: model, env, finish_reason, thread_id

It also implements __toString(), so a response can be echoed directly — though checking ok() first is better practice.

Error handling#

The API never throws for a failed request. It returns a failed response.

php
$response = aimogen()->ask( $prompt );

if ( $response->failed() ) {
    error_log( 'Aimogen: ' . $response->error() );
    return $fallback_text;
}

return $response->text();

Two failures are reported before any request is made: Aimogen text generation is not available when the plugin is not loaded, and No AI API key is configured in Aimogen Pro settings.

Practical example#

Generating a meta description on publish, once:

php
add_action( 'transition_post_status', function ( $new, $old, $post ) {
    if ( $new !== 'publish' || $old === 'publish' || $post->post_type !== 'post' ) {
        return;
    }
    if ( get_post_meta( $post->ID, '_yoast_wpseo_metadesc', true ) ) {
        return;
    }
    if ( ! function_exists( 'aimogen' ) ) {
        return;
    }

    $response = aimogen()->ask(
        "Write a meta description under 155 characters for this article.\n\n" .
        "Title: {$post->post_title}\n\n" .
        wp_strip_all_tags( $post->post_content ),
        array( 'model' => 'gpt-5-mini', 'max_tokens' => 100, 'temperature' => 0.5, 'env' => 'autoMeta' )
    );

    if ( $response->ok() ) {
        update_post_meta( $post->ID, '_yoast_wpseo_metadesc', sanitize_text_field( $response->text() ) );
    }
}, 10, 3 );

Limits and filters apply#

PHP API requests go through the same pipeline as everything else: usage limits, the aiomatic_ai_allowed filter, prompt and reply filters, Reliability Mode and usage logging.

That means your integration is subject to configured limits, which is usually what you want. It also means your own filters will see these requests.

Still stuck? Open a support ticket and include the diagnostics from Aimogen Pro › System & Logs › System Info.