Skip to main content

​
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
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

Register an HTTPS endpoint to be notified when jobs finish.

Error handling

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