> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> Python SDK for Tinfoil's secure AI inference API

> [card] [View on GitHub](https://github.com/tinfoilsh/tinfoil-python)
>
> tinfoilsh/tinfoil-python

## Overview

The Tinfoil Python SDK is a wrapper around the [OpenAI Python client](https://github.com/openai/openai-python) that provides secure communication with Tinfoil enclaves. It has the same API as the OpenAI SDK with additional security features including automatic verification that the endpoint is running in a secure Tinfoil enclave, TLS certificate pinning, and attestation validation.

## Installation

```bash theme={"dark"}
pip install tinfoil
```

## Migration from OpenAI

Migrating from OpenAI to Tinfoil is straightforward:

```diff theme={"dark"}
# Before (OpenAI)
- from openai import OpenAI
- client = OpenAI(api_key="OPENAI_API_KEY")

# After (Tinfoil)
+ from tinfoil import TinfoilAI
+ client = TinfoilAI(api_key="TINFOIL_API_KEY")
```

All method signatures and response formats remain the same.

## Model Examples

Below are specific examples for each supported model. Click on any model to see its configuration and usage example.

### Chat Models

> [accordion] GLM-5.3
>
> ```python theme={"dark"}
> import os
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Complex reasoning task
> response = client.chat.completions.create(
>     model="glm-5-3",
>     messages=[
>         {
>             "role": "user",
>             "content": "Solve this step by step: If a train travels 120 miles in 2 hours, and then increases its speed by 25% for the next 3 hours, how far does it travel in total?"
>         }
>     ]
> )
>
> print(response.choices[0].message.content)
> ```

> [accordion] Gemma 4 31B
>
> ```python theme={"dark"}
> import os
> import base64
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Image analysis
> with open("image.jpg", "rb") as image_file:
>     base64_image = base64.b64encode(image_file.read()).decode('utf-8')
>
> response = client.chat.completions.create(
>     model="gemma4-31b",
>     messages=[
>         {
>             "role": "user",
>             "content": [
>                 {"type": "text", "text": "What's in this image?"},
>                 {
>                     "type": "image_url",
>                     "image_url": {
>                         "url": f"data:image/jpeg;base64,{base64_image}"
>                     }
>                 }
>             ]
>         }
>     ]
> )
>
> print(response.choices[0].message.content)
> ```

> [accordion] Llama 3.3 70B
>
> ```python theme={"dark"}
> import os
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Conversational AI
> response = client.chat.completions.create(
>     model="llama3-3-70b",
>     messages=[
>         {
>             "role": "user",
>             "content": "What are the key differences between renewable and non-renewable energy sources?"
>         }
>     ]
> )
>
> print(response.choices[0].message.content)
> ```

> [accordion] GPT-OSS 120B
>
> ```python theme={"dark"}
> import os
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Advanced reasoning with configurable effort levels
> response = client.chat.completions.create(
>     model="gpt-oss-120b",
>     messages=[
>         {
>             "role": "user",
>             "content": "Analyze the trade-offs between different database architectures for a high-traffic e-commerce platform."
>         }
>     ]
> )
>
> print(response.choices[0].message.content)
> ```

### Audio Models

> [accordion] Voxtral Small 24B
>
> #### Transcription
>
> ```python theme={"dark"}
> import os
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Audio transcription
> with open("meeting_recording.mp3", "rb") as audio_file:
>     transcription = client.audio.transcriptions.create(
>         file=audio_file,
>         model="voxtral-small-24b",
>         language="en",  # Optional: specify language for better accuracy
>         prompt="This is a business meeting discussing quarterly results"  # Optional: provide context
>     )
>
> print("Transcription:", transcription.text)
> ```
>
> #### Audio Q\&A
>
> ```python theme={"dark"}
> import os
> import base64
> from tinfoil import TinfoilAI
>
> client = TinfoilAI(api_key=os.getenv("TINFOIL_API_KEY"))
>
> # Load audio and encode as base64
> with open("audio.mp3", "rb") as f:
>     audio_base64 = base64.b64encode(f.read()).decode("utf-8")
>
> response = client.chat.completions.create(
>     model="voxtral-small-24b",
>     messages=[{
>         "role": "user",
>         "content": [
>             {"type": "text", "text": "What is the speaker talking about in this audio?"},
>             {
>                 "type": "input_audio",
>                 "input_audio": {"data": audio_base64, "format": "mp3"}
>             }
>         ]
>     }]
> )
>
> print(response.choices[0].message.content)
> ```

### Embedding Models

> [accordion] Nomic Embed Text
>
> ```python theme={"dark"}
> import os
> from tinfoil import TinfoilAI
> import numpy as np
>
> client = TinfoilAI(
>     api_key=os.getenv("TINFOIL_API_KEY")
> )
>
> # Example: Generate embeddings for similarity search
> documents = [
>     "Artificial intelligence is transforming modern technology.",
>     "Machine learning enables computers to learn from data.",
>     "The weather today is sunny and warm.",
>     "Deep learning uses neural networks with multiple layers."
> ]
>
> # Generate embeddings for all documents
> embeddings = []
> for doc in documents:
>     response = client.embeddings.create(
>         model="nomic-embed-text",
>         input=doc,
>         encoding_format="float"
>     )
>     embeddings.append(response.data[0].embedding)
>
> # Calculate similarity between first two documents
> emb1 = np.array(embeddings[0])
> emb2 = np.array(embeddings[1])
> similarity = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))
>
> print(f"Similarity between first two AI-related documents: {similarity:.3f}")
> print(f"Embedding dimension: {len(embeddings[0])}")
> ```

## Async Usage

Simply import `AsyncTinfoilAI` instead of `TinfoilAI` and use `await` with each API call:

```python theme={"dark"}
import os
import asyncio
from tinfoil import AsyncTinfoilAI

client = AsyncTinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

async def main() -> None:
    # start a streaming chat completion
    stream = await client.chat.completions.create(
        model="<MODEL_NAME>",
        messages=[{"role": "user", "content": "Say this is a test"}],
        stream=True,
    )
    async for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="", flush=True)
    print()

asyncio.run(main())
```

Functionality between the synchronous and asynchronous clients is otherwise identical.

## API Documentation

This library is a drop-in replacement for the [official OpenAI Python client](https://github.com/openai/openai-python) that can be used with Tinfoil. All methods and types are identical. See the [OpenAI Python client documentation](https://platform.openai.com/docs/api-reference) for complete API usage and documentation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.