Documentation AIME API Client Interface

class aime_api_client_interface.ModelAPI(api_server, endpoint_name, user=None, key=None, session=None, output_format='base64', output_type='image')

An interface for interacting with the AIME ML API server.

Parameters:

api_server (str) – The base URL of the API server.
endpoint_name (str) – The name of the API endpoint.
session (aiohttp.ClientSession) – Give existing session to ModelApi API to make login request in given session. Defaults to None.

api_server

The base URL of the API server.

Type:: str

endpoint_name

The name of the specific API endpoint.

Type:: str

client_session_auth_key

The authentication key for the client session, obtained from do_api_login.

Type:: str

Examples

Synchronous with progress callback:

from python_api_client_interface import ModelAPI

def progress_callback(progress_info, progress_data):
    process_progress_info(progress_info)
    process_progress_data(progress_data)

model_api = ModelAPI('https://api.aime.team', 'llama2_chat', 'user_name', 'user_key')
model_api.do_api_login()
result = model_api.do_api_request(params, progress_callback)
result_2 = model_api.do_api_request(params, progress_callback)
...

Asynchronous with asynchronous callbacks:

import asyncio
from python_api_client_interface import ModelAPI

async def result_callback(result):
    await process_result(result)

async def progress_callback(progress_info, progress_data):
    await process_progress_info(progress_info)
    await process_progress_data(progress_data)

async def progress_error_callback(error_description):
    print(error_description)

async def main():
    model_api = modelAPI('https://api.aime.team', 'llama2_chat', 'user_name', 'user_key')
    await model_api.do_api_login()
    result = await model_api.do_api_request(params, result_callback, progress_callback)
    result2 = await model_api.do_api_request(params, result_callback, progress_callback)
    ...
    await model_api.close_session()

asynchio.run(main())

Asynchronous with synchronous callbacks:

import asyncio
from python_api_client_interface import ModelAPI

sync def result_callback(result):
    process_result(result)

def progress_callback(progress_info, progress_data):
    process_progress_info(progress_info)
    process_progress_data(progress_data)

def progress_error_callback(error_description):
    print(error_description)

async def main():
    model_api = modelAPI('https://api.aime.team', 'llama2_chat', 'user_name', 'user_key')
    await model_api.do_api_login()
    result = await model_api.do_api_request(params, result_callback, progress_callback)
    result2 = await model_api.do_api_request(params, result_callback, progress_callback)
    ...
    await model_api.close_session()

asynchio.run(main())

Asynchronous generator:

import asyncio
from python_api_client_interface import ModelAPI

async def main():
    model_api = modelAPI('https://api.aime.team', 'llama2_chat', 'user_name', 'user_key')
    await model_api.do_api_login()
    output_generator = model_api.get_api_request_generator()
    async for output in output_generator:
        if not output.get('job_state') == 'done':
            process_progress_data(output)
        else:
            process_job_result(output)
asynchio.run(main())

async do_api_login_async(user=None, key=None, result_callback=None, error_callback=None, session=None)

Asynchronous client login to API server and obtain an authentication key.

Parameters:

user (str) – The name of the user
key (str) – The user related key
result_callback (callable or coroutine) – Callback function or coroutine with the obtained client_session_auth_key as argument. Accepts synchronous functions and asynchrouns couroutines. Defaults to None.
error_callback (callable or coroutine) – Accepts synchronous functions and asynchrouns couroutines. Prevents ConnectionError. Defaults to None.
session (aiohttp.ClientSession) – Give existing session to ModelApi API to make login request in given session. Defaults to None.

Raises:

ConnectionError – If there is a connection issue with the API server and no error_callback given.

Returns:

Client session authentication key

Return type:

str

do_api_login(user=None, key=None)

Client login to API server and obtain an authentication key.

Parameters:

user (str) – The name of the user
key (str) – The user related key

Raises:

ConnectionError – If there is a connection issue with the API server.

Returns:

Client session authentication key

Return type:

str

async do_api_request_async(params, result_callback=None, progress_callback=None, request_error_callback=None, progress_error_callback=None, progress_interval=0.3, progress_stream=False, session=None, output_format='base64')

Do an asynchronous API request with optional progress data via asynchronous or synchronous callbacks.

Parameters:

params (dict) – Dictionary with parameters for the the API request like ‘prompt’ or ‘image’.
result_callback (callable or coroutine, optional) – Callback function or coroutine with argument result (dict) to handle the API request result. Accepts synchronous functions and asynchrouns couroutines. Defaults to None
progress_callback (callable or coroutine, optional) – Callback function or coroutine with arguments progress_info (dict) and progress_data (dict) for tracking progress. Accepts synchronous functions and asynchrouns couroutines. Default is None.
request_error_callback (callable or coroutine, optional) – Callback function or coroutine with argument error_description (str) for catching request errors. Accepts synchronous functions and asynchrouns couroutines. Prevents ConnectionError and PermissionError. Defaults to None.
progress_error_callback (callable or coroutine, optional) – Callback function or coroutine with argument error_description (str) for catching progress errors with successful initial request. Accepts synchronous functions and asynchrouns couroutines. Prevents ConnectionErrors during Transmitting. Defaults to None.
progress_interval (int, optional) – Interval in seconds at which progress is checked. Default is {DEFAULT_PROGRESS_INTERVAL}.
progress_stream (bool, optional) – Not implemented yet
session (aiohttp.ClientSession) – Give existing session to ModelApi API to make login request in given session. Defaults to None.

Raises:

ConnectionError – Raised if client couldn’t connect with API sserver and no request_error_callback is given. Also raised if client lost connection during transmitting and no progress_error_callback is given.
PermissionError – Raised if client is not logged in the API server and no error_callback given.
NotImplementedError – If progress_stream != None.

Returns:

Dictionary with job results

Return type:

dict

Examples

Example job result dict in result callback argument or return value:

result = {
    'auth': '<name_of_worker>',
    'compute_duration': 2.4,
    'images': 'data:image/PNG;base64,...'
    'job_id': 'JID3',
    'seed': 1234413214,
    'success': True,
    'text': 'Test output...',
    'total_duration': 2
}

Example progress_callback arguments progress_info and progress_data dictionaries:

progress_info = {
    'job_id': 'JID3',
    'progress': 50,
    'queue_position': 0,
    'estimate': -1
}
progress_data = {
        'info': '<infos from worker about progress',
        'images': 'data:image/PNG;base64,...',
        'text': 'Test outpu...'
}

async get_api_request_generator(params, progress_interval=0.3, session=None, output_format='base64')

Generator function to get request generator, yielding the results

Parameters:

params (dict) – Dictionary with parameters for the the API request.
progress_interval (int, optional) – Interval in seconds at which progress is checked. Defaults to DEFAULT_PROGRESS_INTERVAL.
session (aiohttp.ClientSession) – Give existing session to ModelApi API to make login request in given session. Defaults to None.
output_format (str, optional) – Define a different output_format. Defaults to ‘base64’.

Yields:

dict – Result dictionary containing job and progress results.

Example usage:

output_generator = model_api.get_api_request_generator()
async for output in output_generator:
    process_output(output)
    print(output)

Example output:

{
    'job_id': 'JID01',
    'success': True,
    'job_state': 'started'
},
{
    'job_id': 'JID01',
    'success': True,
    'job_state': 'processing'
    'progress': 55,
    'queue_position': 0,
    'estimate': 43.6
    'progress_data': {
        'text': 'Example generated text',
        'num_generated_tokens': 55,
        'current_context_length': 116,
    },
},
...
{
    'job_id': 'JID01',
    'success': True,
    'job_state': 'done',
    'progress': 100,
    'result_data': {
        'text': 'Example generated final text',
        'num_generated_tokens': 100,
        'current_context_length': 116,
        'max_seq_len': 8000,
        'prompt_length': 17,
        'ep_version': 2,
        'model_name': 'Llama-3-1-70B-Instruct-fp8',
        'auth': 'a4004-2409c89_NVIDIA H100 NVL_0',
        'worker_interface_version': 'AIME-API-Worker-Interface 0.8.5',
        'result_sent_time': 1736785517.1456308,
        'compute_duration': 16.8,
        'total_duration': 17.0,
        'start_time': 1736785499.9088438,
        'start_time_compute': 1736785500.1000788,
        'pending_duration': 0.0004534721374511719,
        'preprocessing_duration': 0.07061362266540527,
        'arrival_time': 1736785500.1973228,
        'finished_time': 1736785516.8741965,
        'result_received_time': 1736785516.9283218
    }
}

do_api_request(params, progress_callback=None, progress_error_callback=None, progress_interval=0.3, progress_stream=None)

Do an synchronous API request with optional progress data via callbacks.

Parameters:

params (dict) – Dictionary with parameters for the the API request like ‘prompt’ or ‘image’
progress_callback (callable, optional) – Callback function or coroutine with arguments progress_info (dict) and progress_data (dict) for receiving progress data. Defaults to None.
progress_error_callback (callable, optional) – Callback function or coroutine with argument error_description (str) for catching progress errors with successful initial request. Prevents ConnectionErrors during Transmitting. Defaults to None.
progress_interval (int, optional) – Interval in seconds at which progress is checked. Default is 300.
progress_stream (int, optional) – Not implemented yet

Raises:

ConnectionError – Raised if client couldn’t connect with API server. Also raised if client lost connection during transmitting and no progress_error_callback given.
PermissionError – Raised if client is not logged in the API server
NotImplementedError – If progress_stream != None

Returns:

Dictionary with request result parameters.

Return type:

dict

Examples

Example job result dict:

result = {
    'auth': '<name_of_worker>',
    'compute_duration': 2.4,
    'images': 'data:image/PNG;base64,...'
    'job_id': 'JID3',
    'seed': 1234413214,
    'success': True,
    'text': 'Test output...',
    'total_duration': 2
}

Example progress_callback arguments progress_info and progress_data dictionaries:

progress_info = {
    'job_id': 'JID3',
    'progress': 50,
    'queue_position': 0,
    'estimate': -1
}
progress_data = {
        'info': '<infos from worker about progress',
        'images': 'data:image/PNG;base64,...',
        'text': 'Test outpu...'
}

setup_session(session)

Open a new session if session is

Parameters:: session (aiohttp.ClientSession) – Give existing session to ModelApi API to make upcoming requests in given session.

async close_session(): Close the aiohttp client session saved in ModelApi().session.

static check_if_valid_base64_string(test_string)

Check if given string is a valid base64-encoded string.

Parameters:: test_string (str) – The string to test.
Returns:: True if the string is a valid base64-encoded string, False otherwise.
Return type:: bool

static get_version()

Parses name and version of AIME API Client Interface with pkg_resources

Returns:: Name and version of AIME API Client Interface
Return type:: str

async aime_api_client_interface.do_api_request_async(api_server, endpoint_name, params, user=None, key=None, result_callback=None, progress_callback=None, request_error_callback=None, progress_error_callback=None, session=None)

A simplified interface for making a single asynchronous API request with do_api_login included.

Parameters:

api_server (str) – The address of the API server
endpoint_name (str) – The name of the API endpoint
params (dict) – Parameters for the API request
user (str) – The name of the user
key (str) – The user related key
result_callback (callback, optional) – Callback function with argument result (dict) to handle the API request result. Defaults to None.
progress_callback (callback, optional) – Callback function with arguments progress_info (dict). Defaults to None. and progress_data (dict) for tracking progress. Defaults to None.
request_error_callback (callback, optional) – Callback function with arguments error_description (str) for catching request errors. Defaults to None.
progress_error_callback (callable or coroutine, optional) – Callback function with arguments error_description (str) for catching progress errors with successful initial request. Accepts synchronous functions and asynchrouns couroutines. Defaults to None.
session (aiohttp.ClientSession) – Give existing session to ModelApi API to make login request in given session. Defaults to None.

Returns:

Dictionary with request result parameters.

Return type:

dict

Raises:

ConnectionError – Raised if client couldn’t connect with API server and no request_error_callback is given. Also raised if client lost connection during transmitting and no progress_error_callback is given.

Examples

Example usage with synchronous callbacks:

import asyncio

def result_callback(result):
    process_result(result)

def progress_callback(progress_info, progress_data):
    process_progress_info(progress_info)
    process_progress_data(progress_data)


asyncio.run(do_api_request('https://api.aime.team', 'llama2_chat', {'text': 'Chat question'}, 'user_name', 'password', result_callback, progress_callback))

Example usage with asynchronous callbacks:

import asyncio

async def result_callback(result):
    await process_result(result)

async def progress_callback(progress_info, progress_data):
    await process_progress_info(progress_info)
    await process_progress_data(progress_data)


result = asyncio.run(do_api_request('https://api.aime.team', 'llama2_chat', {'text': 'Chat question'}, 'user_name', 'password', result_callback, progress_callback))

Example progress result dictionary at start:

progress_result = {
    'job_id': 'JID6',
    'job_state': 'processing',
    'progress': {
        'progress': 0,
        'queue_position': 0
    },
    'success': True
}

Example progress result dictionary while processing:

progress_result = {
    'job_id': 'JID6',
    'job_state': 'processing',
    'progress': {
        'job_id': 'JID6',
        'progress': 50,
        'progress_data': {
            'images': 'base64-string',
            'text': 'Test output'
        },
        'queue_position': 0
    },
    'success': True
}

Example progress_result dictionaries when finished:

progress_result = {
    'job_id': 'JID6',
    'job_result': {
        'auth': 'neo07_GPU0',
        'compute_duration': 2.4,
        'images': 'data:image...',
        'text': 'Test outpu...',
        'total_duration': 2.5
    },
    'job_state': 'done',
    'progress': {
        'job_id': 'JID6',
        'progress': 100,
        'progress_data': {
            'images': 'data:image...',
            'text': 'Test outpu...'
        },
        'queue_position': 0
    },
    'success': True
}

aime_api_client_interface.do_api_request(api_server, endpoint_name, params, user=None, key=None, progress_callback=None, progress_error_callback=None)

A simplified interface for making a single synchronous API request with do_api_login included.

Parameters:

api_server (str) – Address of API server
endpoint_name (str) – Name of endpoint
params (dict) – Dictionary with api request parameters
user (str) – The name of the user
key (str) – The user related key
progress_callback (callback, optional) – Callback function with arguments progress_info (dict) and progress_data (dict) for tracking progress. Defaults to None.
progress_error_callback (callback, optional) – Callback function with argument error_description (str) called if request was successfull but progress got errors. Defaults to None.

Returns:

Dictionary with request result parameters

Return type:

dict

Raises:

ConnectionError – Raised if client couldn’t connect with API server. Also raised if client lost connection during transmitting and no progress_error_callback is given.

Examples

Example usage with progress and progress_error_callback:

import asyncio

def progress_callback(progress_info, progress_data):
    process_progress_info(progress_info)
    process_progress_data(progress_data)

def progress_error_callback(error_description):
    pass

result = do_api_request('https://api.aime.team', 'llama2_chat', {'text': 'Chat question'}, 'user_name', 'password', progress_callback, progress_error_callback)

Example progress result dictionary at start:

progress_result = {
    'job_id': 'JID6',
    'job_state': 'processing',
    'progress': {
        'progress': 0,
        'queue_position': 0
    },
    'success': True
}

Example progress result dictionary while processing:

progress_result = {
    'job_id': 'JID6',
    'job_state': 'processing',
    'progress': {
        'job_id': 'JID6',
        'progress': 50,
        'progress_data': {
            'images': 'base64-string',
            'text': 'Test output'
        },
        'queue_position': 0
    },
    'success': True
}

Example progress_result dictionaries when finished:

progress_result = {
    'job_id': 'JID6',
    'job_result': {
        'auth': 'neo07_GPU0',
        'compute_duration': 2.4,
        'images': 'data:image...',
        'text': 'Test outpu...',
        'total_duration': 2.5
    },
    'job_state': 'done',
    'progress': {
        'job_id': 'JID6',
        'progress': 100,
        'progress_data': {
            'images': 'data:image...',
            'text': 'Test outpu...'
        },
        'queue_position': 0
    },
    'success': True
}