AI21 Python SDK

4.3.0 verified Tue May 12 auth: no python install: verified quickstart: stale

Official Python SDK for AI21 Labs API. Provides access to Jamba models (chat completions, streaming) and legacy J2 Jurassic models (completions). Current version: 4.3.0 (Mar 2026). SDK has two distinct API surfaces — modern Jamba chat completions API and legacy J2/Jurassic API — with different ChatMessage signatures. Jamba models are current; J2 models are legacy.

pip install ai21

Common errors

error ModuleNotFoundError: No module named 'ai21' ↓

cause The 'ai21' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install ai21'.

error AttributeError: module 'ai21' has no attribute 'Completion' ↓

cause The 'Completion' attribute is not available in the 'ai21' module, possibly due to an outdated SDK version or incorrect usage.

fix

Ensure you are using the latest version of the SDK and refer to the updated documentation for correct usage.

error TypeError: AI21Client() takes no arguments ↓

cause Incorrect instantiation of the AI21Client class, possibly due to changes in the SDK's initialization method.

fix

Initialize the client without arguments: 'client = AI21Client()'.

error ImportError: cannot import name 'ChatMessage' from 'ai21.models.chat' ↓

cause The 'ChatMessage' class is not found in the 'ai21.models.chat' module, likely due to changes in the SDK's structure.

fix

Check the latest SDK documentation for the correct import path or class name.

error ValueError: Invalid model name 'j2-ultra' ↓

cause The specified model name 'j2-ultra' is invalid or deprecated.

fix

Use a valid model name as per the latest SDK documentation, such as 'jamba-large'.

Warnings

breaking Two ChatMessage classes exist: ai21.models.chat.ChatMessage (Jamba, uses content=) and ai21.models.ChatMessage (J2/legacy, uses text= and RoleType). Mixing them causes TypeError. ↓

fix For Jamba models use: from ai21.models.chat import ChatMessage with content= and string roles. For J2 legacy: from ai21.models import ChatMessage with text= and RoleType.

breaking Old J2/Jurassic API uses client.chat.create() with system= as separate param. New Jamba API uses client.chat.completions.create() with system message inside messages list. Completely different method name. ↓

fix For Jamba: client.chat.completions.create(messages=[...]). For J2: client.chat.create(system=..., messages=[...]).

gotcha LLMs trained pre-2024 have no knowledge of Jamba models. Will generate J2 Jurassic patterns (model='j2-ultra', RoleType, text= parameter) which are legacy and will be deprecated. ↓

fix Use Jamba models: 'jamba-large', 'jamba-mini'. Use content= not text=. Use string roles not RoleType enum.

gotcha API key env var is AI21_API_KEY. SDK reads it automatically if not passed explicitly to AI21Client(). ↓

fix export AI21_API_KEY=your_key or pass api_key= to AI21Client().

deprecated J2 Jurassic models (j2-ultra, j2-mid, j2-light) are legacy. Jamba is the current model family. New features only on Jamba. ↓

fix Migrate to jamba-large or jamba-mini for new projects.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.83s 33.0M

3.10 slim (glibc) - - 0.63s 33M

3.11 alpine (musl) - - 1.09s 36.0M

3.11 slim (glibc) - - 0.95s 36M

3.12 alpine (musl) - - 1.41s 27.5M

3.12 slim (glibc) - - 1.39s 27M

3.13 alpine (musl) - - 1.18s 27.2M

3.13 slim (glibc) - - 1.17s 27M

3.9 alpine (musl) - - 0.80s 32.3M

3.9 slim (glibc) - - 0.81s 32M

Imports

AI21Client (Jamba — current)

wrong

from ai21 import AI21Client
from ai21.models import RoleType, ChatMessage

messages = [
    ChatMessage(text='What is AI21?', role=RoleType.USER)
]
client.chat.create(system='...', messages=messages, model='jamba-large')

correct

from ai21 import AI21Client
from ai21.models.chat import ChatMessage

client = AI21Client()  # reads AI21_API_KEY from env

response = client.chat.completions.create(
    model='jamba-large',
    messages=[
        ChatMessage(content='You are a helpful assistant.', role='system'),
        ChatMessage(content='What is AI21 Labs?', role='user')
    ],
    max_tokens=200
)
print(response.choices[0].message.content)

Two ChatMessage APIs exist in the same package. New Jamba API uses content= parameter and string roles ('user', 'assistant'). Old J2 API uses text= parameter and RoleType enum. Wrong ChatMessage for wrong API raises TypeError or ValidationError.

AsyncAI21Client

wrong

from ai21 import AI21Client  # sync client in async context

correct

from ai21 import AsyncAI21Client
from ai21.models.chat import ChatMessage
import asyncio

client = AsyncAI21Client()

async def main():
    response = await client.chat.completions.create(
        model='jamba-mini',
        messages=[ChatMessage(content='Hello', role='user')]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

Use AsyncAI21Client for async. Same import path, different class.

Quickstart stale last tested: 2026-04-23

Minimal AI21 Jamba chat completion using ai21 SDK 4.x.

# pip install ai21
from ai21 import AI21Client
from ai21.models.chat import ChatMessage
import os

client = AI21Client()  # reads AI21_API_KEY env var

response = client.chat.completions.create(
    model='jamba-large',
    messages=[
        ChatMessage(content='You are a helpful assistant.', role='system'),
        ChatMessage(content='Explain large language models briefly.', role='user')
    ],
    max_tokens=150,
    temperature=0.7
)
print(response.choices[0].message.content)