Python SDK
Install and configure the official Python client.
On this page
The official caedral PyPI package is a synchronous Python client for the API gateway. Authenticate with api_key (cd_live_…). Chat completions may pass an optional notre object with mode off or auto and telemetry. Notre Runtime is included on every plan and applied on eligible POST /v1/chat/completions when the platform runs Notre — not on embeddings, rerank, voice, or images. Install with pip install caedral — repository: github.com/trycaedral/caedral (directory sdk-python).
Installation
pip install caedralQuickstart
from caedral import Caedral with Caedral(api_key="cd_live_...", base_url="http://localhost:5001") as caedral: completion = caedral.chat.completions.create( model="anthropic/claude-haiku-4.5", messages=[{"role": "user", "content": "Hello!"}], ) print(completion.choices[0].message["content"])| Parameter | Default | Description |
|---|---|---|
| api_key | — | Required. Your cd_live_... API key |
| base_url | https://api.caedral.com | API gateway base URL |
| max_retries | 3 | Retries for idempotent GET requests |
| timeout | 120.0 | Request timeout in seconds |
caedral.chat.completions.create(...)
response = caedral.chat.completions.create( model="anthropic/claude-sonnet-4.5", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain quantum computing briefly."}, ], temperature=0.7, max_tokens=500,)print(response.choices[0].message["content"])Streaming
stream = caedral.chat.completions.create( model="anthropic/claude-haiku-4.5", messages=[{"role": "user", "content": "Write a haiku about code."}], stream=True,) for chunk in stream: delta = chunk.choices[0].delta.get("content") if delta: print(delta, end="", flush=True)print()caedral.models.list()
models = caedral.models.list()for model in models.data: print(model.id, model.name, "free tier" if model.is_free else "paid")caedral.usage.get()
usage = caedral.usage.get()print("Account status:", usage.accountStatus)print("External pool used:", usage.pools.external.percentUsed, "%")caedral.embeddings.create(...)
result = caedral.embeddings.create( model="caedral-embed", input="Caedral unifies frontier models behind one API.",)print(len(result.data[0].embedding))caedral.images.generate(...)
image = caedral.images.generate( model="caedral-vision", prompt="A minimal geometric logo on a dark background",)print(image.data[0].url or "b64 payload returned")caedral.audio.generate(...)
audio = caedral.audio.generate( model="caedral-voice", input="Welcome to Caedral.", voice="alloy",)print(audio.model)caedral.rerank.create(...)
ranked = caedral.rerank.create( model="caedral-rerank", query="billing and subscription plans", documents=[ "Caedral API usage draws from subscription pools.", "The API gateway runs on port 5001 in local dev.", ], top_n=2,)for item in ranked.results: print(item.index, item.relevance_score)Errors
from caedral import CaedralAPIError try: caedral.chat.completions.create( model="anthropic/claude-haiku-4.5", messages=[{"role": "user", "content": "Hi"}], )except CaedralAPIError as err: print(err.status_code, err.type, err.message)