Apertis Python SDK

Official Python SDK for the Apertis AI API.

Installation

pip install apertis

Quick Start

from apertis import Apertis

client = Apertis(api_key="your-api-key")
# Or set APERTIS_API_KEY environment variable

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Features

Sync and Async Support: Both synchronous and asynchronous clients
Streaming: Real-time streaming for chat completions
Tool Calling: Function/tool calling support
Embeddings: Text embedding generation
Vision/Image: Analyze images with multimodal models
Audio I/O: Audio input and output support
Audio API: Text to speech, transcription and translation (client.audio)
Video: Video content analysis
Web Search: Real-time web search integration
Context Compression: Compress long conversation history to save tokens
Reasoning Mode: Chain-of-thought reasoning support
Extended Thinking: Deep thinking for complex problems
Messages API: Anthropic-native message format
Responses API: OpenAI Responses API format
Rerank API: Document reranking for RAG (not currently available, see below)
Models API: List and retrieve available models
Type Hints: Full type annotations for IDE support
Automatic Retries: Built-in retry logic for transient errors

Usage

Chat Completions

from apertis import Apertis

client = Apertis()

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    temperature=0.7,
    max_tokens=100,
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")

Streaming

stream = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Vision / Image Analysis

Analyze images using multimodal models with the convenience method:

# Using image URL
response = client.chat.completions.create_with_image(
    model="gpt-5.4",
    prompt="What is in this image?",
    image="https://example.com/photo.jpg",
)
print(response.choices[0].message.content)

# Using local file (automatically base64 encoded)
response = client.chat.completions.create_with_image(
    model="gpt-5.4",
    prompt="Describe this image",
    image="/path/to/local/image.png",
)

# Multiple images
response = client.chat.completions.create_with_image(
    model="gpt-5.4",
    prompt="Compare these images",
    image=["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
    system="Be detailed in your comparison.",
)

Or use the standard API format:

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
        ]
    }]
)

Audio Input/Output

# Audio input
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What does this audio say?"},
            {"type": "input_audio", "input_audio": {"data": "base64_audio_data", "format": "wav"}}
        ]
    }]
)

# Audio output
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Say hello in a friendly voice"}],
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "wav"},
)
print(response.choices[0].message.audio.transcript)

Speech, Transcription and Translation

# Text to speech
speech = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    input="Hello from Apertis!",
    voice="alloy",
)
speech.write_to_file("hello.mp3")

# Speech to text: pass a path, an open file, bytes, or (filename, bytes)
transcript = client.audio.transcriptions.create(file="meeting.mp3", model="whisper-1")
print(transcript.text)

# Subtitles come back as plain text
srt = client.audio.transcriptions.create(
    file="meeting.mp3", model="whisper-1", response_format="srt"
)

# Translate speech into English text
translation = client.audio.translations.create(file="bonjour.m4a", model="whisper-1")
print(translation.text)

Web Search

Enable real-time web search for a non-free model by appending :web to its model ID. Use the documented result-count and content-length fields, then read the returned sources:

response = client.chat.completions.create(
    model="gpt-5.5:web",
    messages=[{"role": "user", "content": "Latest Python releases?"}],
    web_results_count=5,
    web_content_length="medium",
)

for source in response.web_sources or []:
    print(f"{source.title}: {source.url}")

The legacy web_search_options argument and message-level annotations remain available for existing clients. Do not combine the legacy options with web_results_count or web_content_length in one request.

Reasoning Mode

Enable chain-of-thought reasoning for complex problems:

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[{"role": "user", "content": "How many r's are in strawberry?"}],
    reasoning={"enabled": True, "effort": "high"},
)

# Or use shorthand
response = client.chat.completions.create(
    model="glm-5.1",
    messages=[{"role": "user", "content": "Solve this math problem..."}],
    reasoning_effort="high",
)

Extended Thinking (Gemini)

Use extended thinking for deep analysis:

response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Analyze this complex problem..."}],
    thinking={"type": "enabled"},
)

# With custom thinking budget
response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=[{"role": "user", "content": "Deep analysis needed..."}],
    extra_body={
        "google": {"thinking_config": {"thinking_budget": 10240}}
    },
)

Context Compression

Reduce token usage in long conversations by compressing older message history:

# Chat Completions with compression
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "user", "content": "Explain distributed systems"},
        {"role": "assistant", "content": "Distributed systems are..."},
        {"role": "user", "content": "Summarize the key points"},
    ],
    compression={
        "enabled": True,
        "strategy": "aggressive",  # "on", "conservative", or "aggressive"
        "threshold": 8000,         # Token threshold to trigger compression
        "keep_turns": 6,           # Recent turns to always preserve
        "model": "auto",           # Compression model ("auto" or specific model)
    },
)

# Minimal config — just enable it
response = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Hello!"}],
    compression={"enabled": True},
)

# Also works with Messages API and Responses API
message = client.messages.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=1024,
    compression={"enabled": True, "strategy": "conservative"},
)

Async Usage

import asyncio
from apertis import AsyncApertis

async def main():
    client = AsyncApertis()

    response = await client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

    await client.close()

asyncio.run(main())

Async Streaming

async def stream_example():
    client = AsyncApertis()

    stream = await client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Tell me a joke"}],
        stream=True,
    )

    async for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)

    await client.close()

Tool Calling

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city name"
                    }
                },
                "required": ["location"]
            }
        }
    }],
    tool_choice="auto",
    parallel_tool_calls=True,  # let the model call several tools in one turn
)

if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        print(f"Function: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")

Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello, world!",
)

embedding = response.data[0].embedding
print(f"Embedding dimension: {len(embedding)}")

Batch Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Hello", "World", "How are you?"],
)

for item in response.data:
    print(f"Index {item.index}: {len(item.embedding)} dimensions")

Models API

List and retrieve available models:

# List all models
models = client.models.list()
for model in models.data:
    print(f"{model.id} - owned by {model.owned_by}")

# Retrieve specific model
model = client.models.retrieve("gpt-5.4")
print(f"Model: {model.id}, Created: {model.created}")

Messages API (Anthropic Format)

Use Anthropic-native message format:

message = client.messages.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello, Claude!"}],
    max_tokens=1024,
    system="You are a helpful assistant.",
)

print(message.content[0].text)
print(f"Stop reason: {message.stop_reason}")

With tool use:

message = client.messages.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a location",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }],
)

if message.stop_reason == "tool_use":
    for block in message.content:
        if block.type == "tool_use":
            print(f"Tool: {block.name}, Input: {block.input}")

Streaming and extended thinking:

stream = client.messages.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What is 27 * 453?"}],
    max_tokens=4096,
    thinking={"type": "enabled", "budget_tokens": 2048},
    stream=True,
)

for event in stream:
    if event.type == "content_block_delta":
        if event.delta.type == "thinking_delta":
            print(event.delta.thinking, end="")
        elif event.delta.type == "text_delta":
            print(event.delta.text, end="")

Without stream, thinking arrives as thinking blocks in message.content, before the text. extra_body={...} merges extra fields into the top level of the request.

Responses API

Use OpenAI Responses API format for advanced use cases:

response = client.responses.create(
    model="gpt-5.4",
    input="Write a haiku about programming",
)

print(response.output_text)

# `output` also holds reasoning and function_call items, so iterate by type
for item in response.output:
    print(item.type)

# Structured input uses the Responses API part types
response = client.responses.create(
    model="gpt-5.4",
    input=[{
        "type": "message",
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What is in this image?"},
            {"type": "input_image", "image_url": "https://example.com/cat.png"},
        ],
    }],
)

# Streaming: events keep their Responses API type and fields
stream = client.responses.create(
    model="gpt-5.4",
    input="Write a haiku about programming",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

# With reasoning
response = client.responses.create(
    model="gpt-5.4",
    input="Solve this complex problem...",
    reasoning={"effort": "high"},
)

Rerank API

Not currently available. The Apertis API does not serve POST /v1/rerank yet, so client.rerank.create() returns a 404 NotFoundError and emits a DeprecationWarning. The interface below is kept for when the endpoint ships.

results = client.rerank.create(
    model="BAAI/bge-reranker-v2-m3",
    query="What is machine learning?",
    documents=[
        "Machine learning is a subset of AI.",
        "The weather is nice today.",
        "Deep learning uses neural networks.",
    ],
    top_n=2,
)

for result in results.results:
    print(f"Index {result.index}: Score {result.relevance_score}")

# With document text in results
results = client.rerank.create(
    model="BAAI/bge-reranker-v2-m3",
    query="Python programming",
    documents=["Python is great", "Java is popular"],
    return_documents=True,
)

for result in results.results:
    print(f"{result.document}: {result.relevance_score}")

Error Handling

from apertis import (
    Apertis,
    ApertisError,
    APIError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

client = Apertis()

try:
    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError as e:
    print(f"Invalid API key: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Status: {e.status_code}")
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")
except ApertisError as e:
    print(f"Error: {e.message}")

Configuration

client = Apertis(
    api_key="your-api-key",           # Or use APERTIS_API_KEY env var
    base_url="https://api.apertis.ai/v1",  # Custom base URL
    timeout=60.0,                      # Request timeout in seconds
    max_retries=2,                     # Number of retries for failed requests
    default_headers={"X-Custom": "value"},  # Additional headers
)

Context Manager

with Apertis() as client:
    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
# Client is automatically closed

# Async version
async with AsyncApertis() as client:
    response = await client.chat.completions.create(...)

Available Models

Any model available on Apertis AI, including:

Chat Models

OpenAI: gpt-5.4, gpt-5.1, gpt-5.3-codex
Anthropic: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4.5
Google: gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-flash-preview
Other: glm-5.1, minimax-m2.7, and 500+ more models

Reasoning Models

glm-5.1 (with reasoning enabled)

Search Models

gpt-5-search-api

Embedding Models

text-embedding-3-small, text-embedding-3-large

Rerank Models

Listed in the model catalog, but not callable until the rerank endpoint ships.

BAAI/bge-reranker-v2-m3
Qwen/Qwen3-Reranker-0.6B, Qwen/Qwen3-Reranker-4B, Qwen/Qwen3-Reranker-8B

Requirements

Python 3.9+
httpx
pydantic

Publishing

The repository publishes only from the manual Publish to PyPI workflow. Configure PyPI Trusted Publishing for the apertis-ai/python-sdk repository, workflow .github/workflows/publish.yml, and the pypi environment before dispatching it with the publish confirmation value.

Changelog

v0.4.1

Type Responses API input parts: ResponseInputText (input_text), ResponseInputImage (input_image) and ResponseInputFile (input_file). The old text / image part types still type-check.
Add budget_tokens to ThinkingConfig.
Add stream to responses.create(): stream=True returns ResponseStreamEvent events, and an error event raises APIError.

v0.4.0

Add client.audio: speech.create() (binary audio with write_to_file()), transcriptions.create() and translations.create() (multipart uploads).
Add stream, thinking and extra_body to messages.create(), with typed stream events and thinking / redacted_thinking content blocks.
Streamed requests that fail with an HTTP error now raise APIError (previously httpx.ResponseNotRead).
Parse real Responses API output: output_text and refusal message parts, reasoning and function_call items, and unmodelled item types (kept as ResponseUnknownOutputItem). Add Response.output_text and the queued / in_progress statuses.
Add parallel_tool_calls and max_completion_tokens to chat.completions.create().
Mark rerank.create() as unavailable: it emits a DeprecationWarning, because the Apertis API does not serve POST /v1/rerank.

v0.3.0

Add the current Apertis Web Search request fields and typed top-level sources while retaining legacy Web Search options for compatibility.

v0.2.2

Updated model identifiers to latest versions (gpt-5.4, claude-opus-4-6, claude-sonnet-4-6, glm-5.1)
Added support for gpt-5.3-codex and minimax-m2.7 models
Removed deprecated model references (gpt-4o, o1-pro, gpt-5-pro)

v0.2.1

Fixed missing compression parameter in AsyncCompletions overloads

v0.2.0

Added Vision/Image support with create_with_image() convenience method
Added Audio input/output support
Added Video content support
Added Web Search with create_with_web_search() convenience method
Added Reasoning Mode support
Added Extended Thinking (Gemini) support
Added Models API (client.models.list(), client.models.retrieve())
Added Responses API (client.responses.create())
Added Messages API (client.messages.create()) for Anthropic format
Added Rerank API (client.rerank.create())
Added helper utilities for base64 encoding

v0.1.1

Fixed API response compatibility issues

v0.1.0

Initial release with Chat Completions, Streaming, Tool Calling, and Embeddings

License

Apache 2.0 - see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apertis		apertis
openspec		openspec
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile.test		Dockerfile.test
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation