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#
$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:
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.
$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.
$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.
$response = aimogen()->see(
'Describe what is in this image, in one sentence.',
'https://example.com/photo.jpg'
);paint( $prompt, $args = array() )#
Image generation.
$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.
$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 itsay() 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():
| Argument | Default | Meaning |
|---|---|---|
model | The configured default | Falls back to the default if the model is not recognised |
max_tokens / tokens | Computed | Caps the output budget |
temperature | 1 | |
top_p | 1 | |
presence_penalty | 0 | |
frequency_penalty | 0 | |
is_chat | true | Chat versus completion |
env | Per method | The environment label recorded in the usage logs |
assistant_id | empty | Use an assistant |
thread_id | empty | Assistants thread |
vision_file | empty | Image URL for vision |
user_question | empty | The user question passed alongside |
role | user | Message role |
embedding_namespace | empty | Retrieval namespace |
function_result | empty | A tool result to feed back |
file_data | empty | File data |
parse_markdown | false | Convert markdown to HTML |
store_data | false | Ask the provider to retain the request |
functions | array() | Forced tool definitions |
mcp_servers | empty | MCP servers to enable |
internet | enabled | Pass false to disable internet access |
embeddings | enabled | Pass false to disable retrieval |
stream | false | Streaming |
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.
| Method | Returns |
|---|---|
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.
$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:
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.
Related#
Still stuck? Open a support ticket and include the diagnostics from Aimogen Pro › System & Logs › System Info.