Equos Python SDK

Equos.ai official Python SDK.

Prerequisites

• Go to Equos Studio.
• Create an organization.
• Create an API Key.

Installation

pip install equos

Features

• Official Python SDK for Equos.ai
• High-level EquosClient grouped by resource (brains, characters, faces, voices, conversations, knowledge_bases, organizations, tokens, health)
• Sync and async variants for every endpoint
• Type-safe generated models for all request / response bodies
• Escape hatch to the low-level generated client for full httpx customization

Quick Start

import os
from equos import EquosClient

client = EquosClient(api_key=os.environ["EQUOS_API_KEY"])

# Health check
print(client.health.check())

# List the first 20 brains
print(client.brains.list())

You don't have an API key? Create one here.

Configuration

By default the client targets https://api.equos.ai. Override the endpoint via EquosOptions:

from equos import EquosClient, EquosOptions

client = EquosClient(
    api_key=os.environ["EQUOS_API_KEY"],
    options=EquosOptions(endpoint="https://develop-api.equos.ai"),
)

API Groups

Every group is available on the EquosClient instance. Each method has an async counterpart suffixed with _async.

client.brains

client.characters

client.faces

client.voices

client.conversations

client.knowledge_bases

client.organizations

client.tokens

client.health

Examples

Create and Fetch a Brain

from equos import EquosClient
from equos.models import CreateEquosBrainRequest

client = EquosClient(api_key="YOUR_API_KEY")

created = client.brains.create(CreateEquosBrainRequest(name="My Brain"))
print(created.id, created.name)

fetched = client.brains.get(created.id)
print(fetched)

Start a Conversation

from equos import EquosClient
from equos.models import CreateEquosConversationRequest

client = EquosClient(api_key="YOUR_API_KEY")

conversation = client.conversations.start(
    CreateEquosConversationRequest(character_id="chr_...")
)
print(conversation.id, conversation.token)

Async Usage

Every method has an _async variant that returns a coroutine:

import asyncio
from equos import EquosClient

async def main():
    client = EquosClient(api_key="YOUR_API_KEY")
    brains = await client.brains.list_async(take=50)
    print(brains)

asyncio.run(main())

Pagination and Filtering

list* endpoints accept take, skip, and client_query:

page = client.characters.list(take=50, skip=0, client_query="external-user-123")

Models and Types

All generated request / response models are re-exported for convenience:

from equos.models import (
    CreateEquosBrainRequest,
    CreateEquosCharacterRequest,
    CreateEquosConversationRequest,
    CreateEquosFaceRequest,
    CreateEquosVoiceRequest,
    CreateKnowledgeBaseRequest,
    CreateDocumentRequest,
    CreateEquosTokenRequest,
    # ...and all response models
)

from equos.types import UNSET, Unset, Response

Low-Level Client

For fine-grained control or endpoints not yet surfaced on EquosClient, use the generated client directly:

from equos.client import AuthenticatedClient
from equos.client.api.brain import get_brain

auth_client = AuthenticatedClient(
    base_url="https://api.equos.ai",
    token="YOUR_API_KEY",
    auth_header_name="x-api-key",
    prefix="",
)

with auth_client as c:
    brain = get_brain.sync(id="brain_id", client=c)
    print(brain)

Each generated endpoint module exposes four callables:

• sync(...) — parsed response, or None
• sync_detailed(...) — Response[Parsed] with status / headers / content
• asyncio(...) / asyncio_detailed(...) — async variants

Advanced httpx Customization

import httpx
from equos.client import AuthenticatedClient

auth_client = AuthenticatedClient(
    base_url="https://api.equos.ai",
    token="YOUR_API_KEY",
    auth_header_name="x-api-key",
    prefix="",
    httpx_args={"timeout": 30.0, "proxies": "http://localhost:8030"},
)

# Or swap in your own httpx.Client
auth_client.set_httpx_client(httpx.Client(base_url="https://api.equos.ai"))

Changelog

See Releases for version history.

Other Equos SDKs

Reach Us

• Equos Slack Community: Join Equos Community Slack
• Support: Support Form

Documentation

• Official Documentation: https://docs.equos.ai
• Equos NodeJS Examples: https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration
• Equos React Examples: https://github.com/EquosAI/equos-examples/blob/main/examples/equos-react-integration/README.md

Authors

• Loïc Combis