/ 
LLM-API-1.0.1
/ LLM::API

NAME

LLM::API - Anthropic API client for Claude language models

SYNOPSIS

use LLM::API;
use CLI::Simple::Utils qw(slurp);

my $llm = LLM::API->new(
  api_key => 'sk-ant-...',
);

# Send a simple text prompt
my $response = $llm->prompt('Summarize the Perl documentation.');

if ( $response->is_success ) {
  print $response->content;
}

# Send a document with a prompt
my $file = 'My/Module.pm';
my $doc  = $llm->document( media_type => 'text', data => slurp($file), title => 'My::Module' );
my $text = $llm->text('Review this perl module');
my $rsp  = $llm->send_prompt( [ $doc, $text ] );

# Retrieve usage and cost data
my $usage = $llm->usage_report( from => '2025-01-01', to => '2025-01-31' );
my $cost  = $llm->cost_report( from => '2025-01-01' );

DESCRIPTION

LLM::API is a client for the Anthropic Claude REST API. It supports sending text and document prompts to Claude models, retrieving model lists, API key information, and querying organizational usage and cost reports.

Authentication is handled by passing an API key at construction time or by setting the LLM_API_KEY environment variable. The environment variable is deleted from the process environment immediately after it is read, as a security measure to prevent accidental exposure to child processes.

CONFIGURATION

The following options may be passed to new():

api_key

  Required. Your Anthropic API key. If not provided as an argument, the
  constructor reads it from the LLM_API_KEY environment variable and then
  deletes that variable from the environment.

model

  Optional. The Claude model identifier to use. Defaults to claude-sonnet-4-6.

max_tokens

  Optional. Maximum number of tokens in the model response. Defaults to 4096.

timeout

  Optional. HTTP request timeout in seconds. Defaults to 300.

version

  Optional. Anthropic API version string sent in the anthropic-version header.
  Defaults to 2023-06-01.

role

  Optional. The message role sent with each request. Defaults to 'user'.

CONSTANTS

The following Readonly constants are exported into the package namespace and may be referenced as LLM::API::CONSTANT_NAME.

$DEFAULT_LLM_MODEL

  The default model: claude-sonnet-4-6.

$LLM_URL_BASE

  Base URL for the Anthropic API: https://api.anthropic.com/v1/

$LLM_COUNT_TOKENS_EP

  Endpoint for the determing the number of tokens in a message.

$LLM_MESSAGES_EP

  Endpoint path for sending messages: 'messages'

$LLM_MODELS_EP

  Endpoint path for listing models: 'models'

$LLM_USAGE_EP

  Endpoint path for usage reports: 'organizations/usage_report/messages'

$LLM_COST_EP

  Endpoint path for cost reports: 'organizations/cost_report'

$LLM_KEYS_EP

  Endpoint path for API key listings: 'organizations/api_keys'

$LLM_MAX_TOKENS

  Default maximum token count for responses: 4096

$LLM_VERSION

  Default Anthropic API version header value: '2023-06-01'

$LLM_ROLE

  Default message role: 'user'

$LLM_TIMEOUT

  Default HTTP timeout in seconds: 300

$LLM_PRICING

  A hash reference mapping model names to two-element array
  references containing the per-token input cost and per-token
  output cost in US dollars.

%LLM_MEDIA_TYPES

  A hash mapping short type names to MIME type strings.
  Supported keys are 'text' (maps to 'text/plain') and 'pdf'
  (maps to 'application/pdf').

METHODS AND SUBROUTINES

new

my $llm = LLM::API->new( api_key => $key );
my $llm = LLM::API->new( \%options );

Constructs and returns a new LLM::API instance. Accepts either a hash of named arguments or a reference to a hash.

The api_key argument is required and may alternatively be supplied via the LLM_API_KEY environment variable. The environment variable is deleted from %ENV immediately after being read.

Dies with an error message if api_key is not provided.

count_input_tokens

my ( $tokens, $cost ) = $llm->count_input_tokens( $content );

Counts the input tokens in the supplied content by querying the Anthropic API token counting endpoint without generating a message response. The argument must be an array reference of content block structures such as those produced by text() and document().

Returns a two-element list: the number of input tokens and the estimated cost in US dollars at the current pricing for the configured model. The cost is calculated by multiplying the token count by the per-token input cost from the pricing table.

Throws an exception if the argument is not an array reference.

send_prompt

my $response = $llm->send_prompt( $content );

Sends a messages request to the Anthropic API. The argument must be an array reference of content block structures such as those produced by text() and document() (see document, text). Returns an LLM::API::Response object. Throws an exception if argument is not an array reference.

Use the is_success method of the response to test for success before accessing response data.

die $response->error
  if !$response->is_success;

send_prompt does not throw exceptions on HTTP failure; instead failure information is contained in the response object.

See LLM::API::Response for detail on response object methods.

prompt

my $response = $llm->prompt( $text_string );

Convenience wrapper around send_prompt(). Wraps the supplied plain text string in a text content block and submits it to the API. Returns an LLM::API::Response object.

text

my $block = $llm->text( $text );

Constructs and returns a text content block hash reference suitable for inclusion in the content array passed to send_prompt().

document

my $block = $llm->document(
  media_type => 'text',   # 'text' or 'pdf'
  data       => $string,  # plain text, or a scalar reference for binary data
  title      => $title,   # optional
);

Constructs and returns a document content block hash reference suitable for inclusion in the content array passed to send_prompt().

When data is a plain scalar string the source type is set to 'text' and the data is used as-is.

When data is a scalar reference the referenced value is base64-encoded using MIME::Base64::encode_base64(), which by default includes newlines every 76. This is the mechanism for submitting PDF files.

The media_type argument accepts the short keys defined in %LLM_MEDIA_TYPES: 'text' or 'pdf'. It defaults to 'text'. Any other value will throw an exception. The corresponding MIME type is resolved internally before the block is constructed.

models

my $data = $llm->models;

Retrieves the list of available models from the Anthropic API. Returns the decoded JSON response as a Perl data structure on success, or throws an exception containing the HTTP response code and HTTP body.

See https://platform.claude.com/docs/en/api/beta/models/list for more details.

api_keys

my $data = $llm->api_keys;

Retrieves the list of API keys for the organization from the Anthropic API. Returns the decoded JSON response as a Perl data structure on success, or throws an exception containing the HTTP response code and HTTP body.

Note: This endpoint requires the use of an admin API key.

See https://platform.claude.com/docs/en/api/admin/api_keys/list for more details.

usage_report

my $data = $llm->usage_report(
  from         => '2025-01-01',          # defaults to today
  to           => '2025-01-31',          # optional end date
  api_key_ids  => [$api_key_id],         # optional array of API key filters
  bucket_width => '1h',                  # optional, defaults to '1h'
);

Queries the Anthropic organizational usage report endpoint for message usage data. The from and to values are date strings accepted in either 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM' format and are converted to RFC 3339 timestamps internally. from defaults to today's local date if not supplied.

Returns the decoded JSON response as a Perl data structure on success, or throws an exception containing the HTTP response code and HTTP body.

See https://platform.claude.com/docs/en/api/admin/usage_report/retrieve_messages for more details.

cost_report

my $data = $llm->cost_report(
  from         => '2025-01-01',          # defaults to today
  to           => '2025-01-31',          # optional end date
  bucket_width => '1d',                  # optional, defaults to '1d'
);

Queries the Anthropic organizational cost report endpoint. Date arguments follow the same rules as usage_report(). The default bucket_width for cost reports is '1d' rather than '1h'.

Returns the decoded JSON response as a Perl data structure on success, or throws an exception containing the HTTP response code and HTTP body.

See https://platform.claude.com/docs/en/api/admin/cost_report/retrieve for more detail.

headers

my $headers = $llm->headers;
my $headers = $llm->headers( 'content-type' => 'application/json' );

Builds and returns a hash reference of HTTP request headers. Always includes the x-api-key and anthropic-version headers. Additional header key-value pairs may be supplied as a flat list and are merged into the returned hash.

pricing

my ( $input_cost, $output_cost ) = $llm->pricing;
my ( $input_cost, $output_cost ) = $llm->pricing( $model_name );

Returns the per-token input and output costs in US dollars for the specified model. Throws an exception of no pricing is available for the model.

Note: Costs are expressed as fractional dollar amounts per single token (for example, 0.000003 for $3 per million).

rfc_3339

my $timestamp = $llm->rfc_3339( '2025-01-15' );
my $timestamp = $llm->rfc_3339( '2025-01-15 14:30' );

Interprets the input date string as local time and converts it to an RFC 3339 formatted UTC timestamp string of the form YYYY-MM-DDTHH:MM:SSZ.

Accepts exactly two input formats:

YYYY-MM-DD
YYYY-MM-DD HH:MM

Throws an exception if an unsupported format is passed.

Returns a formatted timestamp conforming to RFC 3339 if a valid date and format are passed. Throws an exception if passed invalid dates. (see Time::Piece)

query_string

my $qs = $llm->query_string( key => 'value', other => 'data' );

Builds a URL query string from a flat hash of key-value pairs. Values are URI-encoded using URI::Encode. Returns a string of the form 'key=value&other=data'. The order of parameters in the returned string is not guaranteed.

Values can be scalars, arrays or hashes. Arrays and hashes will be expanded in the query string as describe in the examples below.

Array Behavior

When an array reference is passed as a value, each element is added to the query string as a separate parameter with the same key.

$llm->query_string( id => [1, 2] );

Produces: id=1&id=2

Hashes Behavior

When a hash reference is passed as a value, each nested key-value pair becomes an individual query parameter using the nested key as the parameter name, and the outer key is discarded.

$llm->query_string(filters => {status => "active", type => "user"});

Produces: status=active&type=user

now

my $date = $llm->now;

Returns the current local date as a string in 'YYYY-MM-DD' format. Used internally as the default starting date for usage and cost reports.

ACCESSORS

The following read/write accessors are generated by Class::Accessor::Fast using the follow_best_practice naming convention. Use get_NAME to read a value and set_NAME to write it.

get_api_key_getter / set_api_key_getter

  Holds a code reference that returns the API key when called. The API key
  is stored only inside this closure and is not exposed directly as an
  attribute value.

get_max_tokens / set_max_tokens

  Maximum number of tokens the model may return in a single response.

get_model / set_model

  The model identifier string used for API requests.

get_version / set_version

  The Anthropic API version string sent in the anthropic-version request header.

get_role / set_role

  The message role string included in each messages API request.

get_timeout / set_timeout

  The HTTP request timeout in seconds sent to L<HTTP::Tiny> by all API calls.

ENVIRONMENT

LLM_API_KEY

If set, the constructor reads this variable as the API key. The variable is immediately deleted from %ENV after being read to reduce the risk of exposing the key to child processes. Setting both this variable and the api_key constructor argument is allowed; the constructor argument takes precedence

Note: LLM_API_KEY is deleted from the environment as a security measure regardless of whether it is used.

DEBUG

If set to a true value at program startup, Data::Dumper is loaded and its Dumper function is imported into the current namespace. This is intended for development use only and has no effect on API behavior.

CAVEATS

The rfc_3339() method recognizes exactly two date string formats (see "rfc_3339"). Supplying an invalid date string or one that does not conform to two supported formats will raise an exception from Time::Piece::strptime.
The query_string() method does not guarantee parameter ordering. When the Anthropic API requires parameters in a specific order this should not be a concern because HTTP query strings are order-independent, but callers relying on a stable string representation should not depend on the output order.
Pricing constants are hardcoded for claude-sonnet-4-6 and reflect the rates at the time this module was written. Anthropic may change pricing at any time. Verify current rates at https://www.anthropic.com/pricing before relying on these values for billing calculations.

DEPENDENCIES

Class::Accessor::Fast
CLI::Simple::Constants
CLI::Simple::Utils
English
HTTP::Tiny
JSON::PP
LLM::API::Response (provided by this distribution)
MIME::Base64
Readonly
Time::Piece
URI::Encode

SEE ALSO

LLM::API::Response

HTTP::Tiny

Class::Accessor::Fast

JSON::PP

MIME::Base64

Time::Piece

URI::Encode

Readonly

Anthropic API documentation: https://docs.anthropic.com/en/api/

Anthropic pricing: https://www.anthropic.com/pricing

VERSION

This documentation refers to version 1.0.1.

AUTHOR

See the distribution metadata for author information.

LICENSE

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