{"id":147,"library":"ai21","title":"AI21 Python SDK","description":"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.","status":"active","version":"4.3.0","language":"python","source_language":"en","source_url":"https://github.com/AI21Labs/ai21-python","tags":["ai21","jamba","llm","python","chat-completions"],"install":[{"cmd":"pip install ai21","lang":"bash","label":"Python"}],"dependencies":[{"reason":"HTTP client. Installed automatically.","package":"httpx","optional":false}],"imports":[{"note":"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.","wrong":"from ai21 import AI21Client\nfrom ai21.models import RoleType, ChatMessage\n\nmessages = [\n    ChatMessage(text='What is AI21?', role=RoleType.USER)\n]\nclient.chat.create(system='...', messages=messages, model='jamba-large')","symbol":"AI21Client (Jamba — current)","correct":"from ai21 import AI21Client\nfrom ai21.models.chat import ChatMessage\n\nclient = AI21Client()  # reads AI21_API_KEY from env\n\nresponse = client.chat.completions.create(\n    model='jamba-large',\n    messages=[\n        ChatMessage(content='You are a helpful assistant.', role='system'),\n        ChatMessage(content='What is AI21 Labs?', role='user')\n    ],\n    max_tokens=200\n)\nprint(response.choices[0].message.content)"},{"note":"Use AsyncAI21Client for async. Same import path, different class.","wrong":"from ai21 import AI21Client  # sync client in async context","symbol":"AsyncAI21Client","correct":"from ai21 import AsyncAI21Client\nfrom ai21.models.chat import ChatMessage\nimport asyncio\n\nclient = AsyncAI21Client()\n\nasync def main():\n    response = await client.chat.completions.create(\n        model='jamba-mini',\n        messages=[ChatMessage(content='Hello', role='user')]\n    )\n    print(response.choices[0].message.content)\n\nasyncio.run(main())"}],"quickstart":{"code":"# pip install ai21\nfrom ai21 import AI21Client\nfrom ai21.models.chat import ChatMessage\nimport os\n\nclient = AI21Client()  # reads AI21_API_KEY env var\n\nresponse = client.chat.completions.create(\n    model='jamba-large',\n    messages=[\n        ChatMessage(content='You are a helpful assistant.', role='system'),\n        ChatMessage(content='Explain large language models briefly.', role='user')\n    ],\n    max_tokens=150,\n    temperature=0.7\n)\nprint(response.choices[0].message.content)","lang":"python","description":"Minimal AI21 Jamba chat completion using ai21 SDK 4.x."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">= 2.0"},{"fix":"For Jamba: client.chat.completions.create(messages=[...]). For J2: client.chat.create(system=..., messages=[...]).","message":"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.","severity":"breaking","affected_versions":">= 2.0"},{"fix":"Use Jamba models: 'jamba-large', 'jamba-mini'. Use content= not text=. Use string roles not RoleType enum.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"export AI21_API_KEY=your_key or pass api_key= to AI21Client().","message":"API key env var is AI21_API_KEY. SDK reads it automatically if not passed explicitly to AI21Client().","severity":"gotcha","affected_versions":"all"},{"fix":"Migrate to jamba-large or jamba-mini for new projects.","message":"J2 Jurassic models (j2-ultra, j2-mid, j2-light) are legacy. Jamba is the current model family. New features only on Jamba.","severity":"deprecated","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T08:44:30.206Z","next_check":"2026-06-24T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install ai21'.","cause":"The 'ai21' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'ai21'"},{"fix":"Ensure you are using the latest version of the SDK and refer to the updated documentation for correct usage.","cause":"The 'Completion' attribute is not available in the 'ai21' module, possibly due to an outdated SDK version or incorrect usage.","error":"AttributeError: module 'ai21' has no attribute 'Completion'"},{"fix":"Initialize the client without arguments: 'client = AI21Client()'.","cause":"Incorrect instantiation of the AI21Client class, possibly due to changes in the SDK's initialization method.","error":"TypeError: AI21Client() takes no arguments"},{"fix":"Check the latest SDK documentation for the correct import path or class name.","cause":"The 'ChatMessage' class is not found in the 'ai21.models.chat' module, likely due to changes in the SDK's structure.","error":"ImportError: cannot import name 'ChatMessage' from 'ai21.models.chat'"},{"fix":"Use a valid model name as per the latest SDK documentation, such as 'jamba-large'.","cause":"The specified model name 'j2-ultra' is invalid or deprecated.","error":"ValueError: Invalid model name 'j2-ultra'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.83,"mem_mb":14.4,"disk_size":"33.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":14.4,"disk_size":"33M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":15.9,"disk_size":"36.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.95,"mem_mb":15.9,"disk_size":"36M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.41,"mem_mb":15.8,"disk_size":"27.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.39,"mem_mb":15.8,"disk_size":"27M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.18,"mem_mb":19.7,"disk_size":"27.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.17,"mem_mb":19.7,"disk_size":"27M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":14.4,"disk_size":"32.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":14.4,"disk_size":"32M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}