{"id":7916,"library":"aleph-alpha-client","title":"Aleph Alpha Python Client","description":"The `aleph-alpha-client` is the official Python client for interacting with Aleph Alpha's API endpoints. It provides synchronous and asynchronous interfaces to access various AI capabilities, including completion, embedding, evaluation, and tool calling with large language and multimodal models. The library is actively maintained, with frequent releases, and is currently at version 11.5.1.","status":"active","version":"11.5.1","language":"en","source_language":"en","source_url":"https://github.com/Aleph-Alpha/aleph-alpha-client","tags":["AI","LLM","NLP","multimodal","Aleph Alpha","client"],"install":[{"cmd":"pip install aleph-alpha-client","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version range for the library.","package":"python","version":">=3.10,<3.14"}],"imports":[{"note":"Main synchronous client class for API interaction.","symbol":"Client","correct":"from aleph_alpha_client import Client"},{"note":"Main asynchronous client class for API interaction.","symbol":"AsyncClient","correct":"from aleph_alpha_client import AsyncClient"},{"note":"Used to specify parameters for text completion requests.","symbol":"CompletionRequest","correct":"from aleph_alpha_client import CompletionRequest"},{"note":"Base class for constructing prompts, including from text or multimodal items.","symbol":"Prompt","correct":"from aleph_alpha_client import Prompt"},{"note":"As of v3.0.0, `ImagePrompt` was removed; use `Image` for image prompt items instead.","wrong":"from aleph_alpha_client import ImagePrompt","symbol":"Image","correct":"from aleph_alpha_client import Image"},{"note":"`AlephAlphaClient` was deprecated and removed in v3.0.0; use `Client` or `AsyncClient` instead.","wrong":"from aleph_alpha_client import AlephAlphaClient","symbol":"AlephAlphaClient","correct":"from aleph_alpha_client import Client"}],"quickstart":{"code":"import os\nfrom aleph_alpha_client import Client, CompletionRequest, Prompt\n\n# Ensure ALEPH_ALPHA_API_TOKEN is set in your environment variables\napi_token = os.environ.get('ALEPH_ALPHA_API_TOKEN', 'YOUR_API_TOKEN')\nif not api_token or api_token == 'YOUR_API_TOKEN':\n    raise ValueError(\"ALEPH_ALPHA_API_TOKEN environment variable not set or is default. Please set it to your actual API token.\")\n\n# Instantiate the synchronous client\nclient = Client(token=api_token)\n\n# Define the prompt and completion request\nrequest = CompletionRequest(\n    prompt=Prompt.from_text(\"Provide a short description of AI:\"),\n    maximum_tokens=64,\n    model=\"luminous-base\" # Or another available model, e.g., \"pharia-1-llm-7b-control\"\n)\n\ntry:\n    # Send the completion request\n    response = client.complete(request=request, model=request.model)\n    print(response.completions[0].completion)\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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`."},"warnings":[{"fix":"Migrate to `Client` or `AsyncClient` for API interaction. Use `Image` instead of `ImagePrompt` for image-based prompts.","message":"Breaking changes in v3.0.0 removed `AlephAlphaClient` and `AlephAlphaModel`. The class `ImagePrompt` was also removed.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure you are using keyword arguments (e.g., `client.semantic_embed(request=my_request, hosting='cloud')`) or update your positional argument order.","message":"The parameter order for `client.semantic_embed` changed, swapping `hosting` and `request`.","severity":"breaking","affected_versions":"Unspecified in changelog, but occurred prior to v11."},{"fix":"Adjust `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.","message":"The `maximum_tokens` parameter limits the *generated output* length, not the total context window (input + output). Setting it too low can result in truncated responses.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Set 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.","cause":"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.","error":"ValueError: ALEPH_ALPHA_API_TOKEN environment variable not set or is default."},{"fix":"Verify 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.","cause":"The specified model name is incorrect, mistyped, or not available on the default ('cloud') or specified hosting for your account.","error":"aleph_alpha_client.aleph_alpha_client.errors.ModelError: Could not find model with name 'your_model_name' on hosting 'cloud'"},{"fix":"Reduce 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.","cause":"The combined length of your prompt exceeds the maximum token limit allowed by the chosen Aleph Alpha model's context window.","error":"aleph_alpha_client.aleph_alpha_client.errors.ValidationError: prompt is too long: X tokens > Y maximum"}]}