ApiClient

The ApiClient is the low-level interface to the Avatar platform. It manages HTTP communication, authentication token refresh, 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.

Session & authentication

ApiClient.authenticate exchanges user credentials for access/refresh tokens. Tokens are stored internally (auth_tokens) and bearer headers are automatically attached to subsequent requests. If the server issues a refresh token, the client can refresh it lazily when needed.

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

  • auth / jobs / results / datasets / users / etc. – resource facades

Example

from avatars.client import ApiClient
client = ApiClient(base_url="https://instance/api")
client.authenticate("user", "pass")
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.AuthTokens(access: str, refresh: str | None = None)[source]

Bases: object

access: str
refresh: str | None = None
update(resp: LoginResponse) → None[source]
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)[source]

Bases: BaseClient

authenticate(username: str, password: str, timeout: int | None = None) → None[source]
forgotten_password(email: str, timeout: int | None = None) → None[source]
reset_password(email: str, new_password: str, new_password_repeated: str, token: UUID, timeout: int | None = None) → None[source]