Quickstart

1. Get an API key

Open the Kallima dashboard → Settings → API tokens → New token. Copy the token — it starts with ab_ and won’t be shown again.

2. Install the Python SDK

pip install kallima

uv add kallima

The SDK requires Python 3.10+. The only runtime dependency is httpx.

3. Create a client

import os
from kallima import KallimaClient

client = KallimaClient(os.environ["KALLIMA_API_KEY"])

4. Pick a project

Create a project in the dashboard and copy its ID from the URL, or fetch it via the SDK:

project = next(client.projects.list())
project_id = project["id"]

5. Register a source antibody

A source antibody is your parental sequence.

source_ab = client.source_antibodies.create(
    project_id=project_id,
    name="Adalimumab parental",
    species_origin="mouse",
    molecule_type="mab",
    vh_sequence="QVQLVESGGGLVQPGGSLRLSCAASGFTFSDYAMSWVRQAPGKGLEWVSAITWSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRGTTMVPFDYWGQGTLVTVSS",
    vl_sequence="DIQMTQSPSSLSASVGDRVTITCRASQGIRNYLAWYQQKPGKAPKRLIYAASTLQSGVPSRFSGSGSGTDFTLTISSLQPEDVATYYCQRYNRAPYTFGQGTKVEIK",
)

6. Create a therapeutic candidate

Creating a candidate automatically creates a baseline variant (v1). The initial_variant_id is what you pass to pipeline jobs.

candidate = client.therapeutic_candidates.create(
    project_id=project_id,
    name="Adalimumab baseline",
    format="mab",
    initial_chains=[
        {"chain_id": "H", "role": "heavy", "variable_sequence": source_ab["vh_sequence"]},
        {"chain_id": "L", "role": "light", "variable_sequence": source_ab["vl_sequence"]},
    ],
    source_antibody_ids=[source_ab["id"]],
)

variant_id = candidate["initial_variant_id"]

7. Submit a humanization

submit() returns a Job object immediately — the job runs asynchronously on GPU.

job = client.humanizations.submit(variant_id=variant_id)
print(job)  # Job(id='...', status='pending', job_type='humanization')

8. Wait for results

job.wait(timeout=120)  # polls until status='completed' or raises TimeoutError

if job.status == "completed":
    for strategy in job.results:
        print(strategy["strategy"], strategy["oasis_score"]["mean"])
else:
    print("Job failed:", job.error)

Full example

import os
from kallima import KallimaClient

client = KallimaClient(os.environ["KALLIMA_API_KEY"])

# Pick the first project (or hard-code a project ID from the dashboard URL)
project_id = next(client.projects.list())["id"]

# Register the parental sequence
source_ab = client.source_antibodies.create(
    project_id=project_id,
    name="My antibody",
    species_origin="mouse",
    molecule_type="mab",
    vh_sequence="QVQLVES...",
    vl_sequence="DIQMTQS...",
)

# Create a therapeutic candidate (baseline variant created automatically)
candidate = client.therapeutic_candidates.create(
    project_id=project_id,
    name="Candidate v1",
    format="mab",
    initial_chains=[
        {"chain_id": "H", "role": "heavy", "variable_sequence": source_ab["vh_sequence"]},
        {"chain_id": "L", "role": "light", "variable_sequence": source_ab["vl_sequence"]},
    ],
    source_antibody_ids=[source_ab["id"]],
)

# Humanize the baseline variant
job = client.humanizations.submit(variant_id=candidate["initial_variant_id"])
job.wait(timeout=120)

for strategy in job.results:
    print(f"{strategy['strategy']:20s}  OASis={strategy['oasis_score']['mean']:.2f}")

What’s next

Batch humanization

Submit 100+ variants at once using client.humanizations.submit_batch().

Structure prediction

Get an ImmuneBuilder PDB + per-residue confidence scores for any variant.

Webhooks

Error handling

How to handle 402 insufficient credits, 429 rate limits, and retries.

Getting started

Guides

API Reference

1. Get an API key

2. Install the Python SDK

3. Create a client

4. Pick a project

5. Register a source antibody

6. Create a therapeutic candidate

7. Submit a humanization

8. Wait for results

Full example

What’s next

Batch humanization

Structure prediction

Webhooks

Error handling

​1. Get an API key

​2. Install the Python SDK

​3. Create a client

​4. Pick a project

​5. Register a source antibody

​6. Create a therapeutic candidate

​7. Submit a humanization

​8. Wait for results

​Full example

​What’s next

Batch humanization

Structure prediction

Webhooks

Error handling

1. Get an API key

2. Install the Python SDK

3. Create a client

4. Pick a project

5. Register a source antibody

6. Create a therapeutic candidate

7. Submit a humanization

8. Wait for results

Full example

What’s next