Install & Compatibility
Where this runs
tested against v11.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.987s · 167.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 12.0s · import 1.920s · 152MB
161MB installed
● package 161MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from aleph_alpha_client import Client
Main synchronous client class for API interaction.
AsyncClient
✓ from aleph_alpha_client import AsyncClient
Main asynchronous client class for API interaction.
CompletionRequest
✓ from aleph_alpha_client import CompletionRequest
Used to specify parameters for text completion requests.
Prompt
✓ from aleph_alpha_client import Prompt
Base class for constructing prompts, including from text or multimodal items.
Image
✓ from aleph_alpha_client import Image
✗ from aleph_alpha_client import ImagePrompt
As of v3.0.0, `ImagePrompt` was removed; use `Image` for image prompt items instead.
AlephAlphaClient
✓ from aleph_alpha_client import Client
✗ from aleph_alpha_client import AlephAlphaClient
`AlephAlphaClient` was deprecated and removed in v3.0.0; use `Client` or `AsyncClient` instead.
This quickstart demonstrates how to initialize the synchronous client, construct a basic text completion request, and print the model's response. It expects the Aleph Alpha API token to be set as an environment variable `ALEPH_ALPHA_API_TOKEN`.
import os
from aleph_alpha_client import Client, CompletionRequest, Prompt
# Ensure ALEPH_ALPHA_API_TOKEN is set in your environment variables
api_token = os.environ.get('ALEPH_ALPHA_API_TOKEN', 'YOUR_API_TOKEN')
if not api_token or api_token == 'YOUR_API_TOKEN':
raise ValueError("ALEPH_ALPHA_API_TOKEN environment variable not set or is default. Please set it to your actual API token.")
# Instantiate the synchronous client
client = Client(token=api_token)
# Define the prompt and completion request
request = CompletionRequest(
prompt=Prompt.from_text("Provide a short description of AI:"),
maximum_tokens=64,
model="luminous-base" # Or another available model, e.g., "pharia-1-llm-7b-control"
)
try:
# Send the completion request
response = client.complete(request=request, model=request.model)
print(response.completions[0].completion)
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingBreaking changes in v3.0.0 removed `AlephAlphaClient` and `AlephAlphaModel`. The class `ImagePrompt` was also removed.fixMigrate to `Client` or `AsyncClient` for API interaction. Use `Image` instead of `ImagePrompt` for image-based prompts.
affects: >=3.0.0
breakingThe parameter order for `client.semantic_embed` changed, swapping `hosting` and `request`.fixEnsure you are using keyword arguments (e.g., `client.semantic_embed(request=my_request, hosting='cloud')`) or update your positional argument order.
affects: Unspecified in changelog, but occurred prior to v11.
gotchaThe `maximum_tokens` parameter limits the *generated output* length, not the total context window (input + output). Setting it too low can result in truncated responses.fixAdjust `maximum_tokens` to allow for the desired response length. Be aware of the model's total context limit when combining a long prompt with `maximum_tokens`. If the prompt alone is too long, it will result in an API error.
affects: All versions
Errors
Common errors & fixes
ValueError: ALEPH_ALPHA_API_TOKEN environment variable not set or is default.
The API client requires an authentication token, which is typically read from the `ALEPH_ALPHA_API_TOKEN` environment variable, but it's either missing or set to a placeholder.
fixSet the `ALEPH_ALPHA_API_TOKEN` environment variable to your actual Aleph Alpha API key. For example: `export ALEPH_ALPHA_API_TOKEN="your_secret_token"` in your shell, or pass it directly to the `Client` constructor.
aleph_alpha_client.aleph_alpha_client.errors.ModelError: Could not find model with name 'your_model_name' on hosting 'cloud'
The specified model name is incorrect, mistyped, or not available on the default ('cloud') or specified hosting for your account.
fixVerify the exact name of the model you intend to use. You can use methods like `client.available_models()` to check for available models and their hostings.
aleph_alpha_client.aleph_alpha_client.errors.ValidationError: prompt is too long: X tokens > Y maximum
The combined length of your prompt exceeds the maximum token limit allowed by the chosen Aleph Alpha model's context window.
fixReduce the length of your input prompt. Consider summarizing parts of the prompt, breaking it into multiple requests, or choosing a model with a larger context window if available.
Upgrade
Version history
11.5.1latest on PyPI · released Jan 30, 2026
Audit
Dependencies
pythonrequiredRequired Python version range for the library.