/ 
Langertha-0.503
/ Langertha::Engine::XAI

NAME

Langertha::Engine::XAI - xAI Grok API

VERSION

version 0.503

SYNOPSIS

use Langertha::Engine::XAI;

my $xai = Langertha::Engine::XAI->new(
    api_key       => $ENV{XAI_API_KEY},
    model         => 'grok-4.7',
    system_prompt => 'You are a helpful assistant',
);

print $xai->simple_chat('Say something nice');

# Streaming
$xai->simple_chat_stream(sub {
    print shift->content;
}, 'Write a poem');

# Tool calling
my $response = await $xai->chat_with_tools_f('Search for Perl modules');

# Image generation (Imagine API)
my $images = $xai->simple_image('A lighthouse at dusk',
    aspect_ratio => '16:9', resolution => '2k');
print $images->[0]{url}, "\n";
# async: await $xai->simple_image_f(...)

DESCRIPTION

Provides access to xAI's Grok models via their OpenAI-compatible API at https://api.x.ai/v1. Composes Langertha::Role::OpenAICompatible with xAI's endpoint and API key handling, plus Langertha::Role::Tools for MCP tool calling.

Grok 4.7 (grok-4.7, the default) is xAI's current flagship general model, with a 500K-token context window and agentic tool calling. model takes any id the API serves, such as the previous default grok-4.6; xAI's models page lists only grok-4.7 today, so check https://docs.x.ai/docs/models before relying on an older id. Grok has no knowledge of current events beyond its training cut-off unless you enable xAI's server-side Web Search / X Search tools.

The engine covers chat, streaming, tool calling, structured output, and image generation with the Imagine API (/v1/images/generations, default model grok-imagine-image-2.0, see "image_request"). xAI's audio (Voice API) and video endpoints are not exposed.

reasoning_effort goes out on chat/completions only with a level the model accepts: low/medium/high/xhigh on grok-4.6 and later, low/medium/high on grok-4.5. Grok always reasons (server default high), so none, minimal and max are dropped and the default applies (see Langertha::Reasoning::Profile).

Set prompt_cache_key to a stable per-conversation value to steer xAI's best-effort prompt-cache routing: it goes out as a prompt_cache_key body field on chat/completions, which xAI plumbs internally to its x-grok-conv-id sticky-routing hint. Check $response->usage->cached_tokens to confirm a cache hit actually happened.

Get your API key at https://console.x.ai/ and set LANGERTHA_XAI_API_KEY in your environment.

THIS API IS WORK IN PROGRESS

image_request

my $request = $xai->image_request('A lighthouse at dusk',
    aspect_ratio    => '16:9',
    resolution      => '2k',
    n               => 2,
    response_format => 'b64_json',
);

Builds the Imagine API request (POST /v1/images/generations) with image_model (default: grok-imagine-image-2.0). xAI's own options pass through as given: aspect_ratio (such as 1:1, 16:9), resolution (1k, 1.5k, 2k), n (up to 10 images) and response_format (url, the default, or b64_json). The OpenAI options size, quality and style are not accepted by xAI and are dropped with a warning. "simple_image" in Langertha::Role::OpenAICompatible and "simple_image_f" in Langertha::Role::ImageGeneration return the ArrayRef of images (url or b64_json each).

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.