ApiClient

The ApiClient is the low-level interface to the Avatar platform. It manages HTTP communication and exposes resource-specific helper objects (jobs, results, datasets, resources, users, etc.).

When to use it

Use the ApiClient directly when you need fine-grained control:

• Custom timeouts or SSL verification settings.

• Injecting a custom httpx.Client instance (e.g. for proxies or advanced retry logic).

• Building tooling or SDK features on top of exposed resources.

For everyday avatarization tasks, the Manager plus a Runner will usually suffice.

Authentication

The ApiClient authenticates using an API key. Pass the key to the constructor and the client automatically sets the Authorization header with the api-key-v1 scheme. API keys are long-lived credentials, so no token refresh is performed.

from avatars.client import ApiClient
client = ApiClient(base_url="https://instance/api", api_key="octopize_apikey...")
# Ready to use immediately.

The key can also be supplied via the AVATAR_API_KEY environment variable instead of the api_key argument.

Key attributes

• base_url – API endpoint root (e.g. https://instance/api)

• timeout – default request timeout (seconds)

• should_verify_ssl – SSL certificate verification toggle

• verify_auth – whether to enforce client-side auth checks

• jobs / results / resources / users / api_keys / etc. – resource facades

Example

from avatars.client import ApiClient
client = ApiClient(base_url="https://instance/api", api_key="octopize_apikey...")
all_jobs = client.jobs.get_jobs().jobs
if all_jobs:
    first = all_jobs[0]
    result = client.results.get_results(first.name)
    print(result)

Detailed reference

class avatars.client.ApiClient(base_url: str | None = None, *, timeout: int | None = None, should_verify_ssl: bool | None = None, verify_auth: bool = True, http_client: Client | None = None, api_key: str | None = None, config: ClientConfig | None = None)

Bases: BaseClient