> ## 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 title="View on GitHub" icon="github" href="https://github.com/tinfoilsh/tinfoil-python" horizontal>
  tinfoilsh/tinfoil-python
</Card>

## 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

<AccordionGroup>
  <Accordion title="GLM-5.2" icon="https://mintcdn.com/tinfoil/GXlDUK5K0yNgB7O7/images/model-icons/zai.png?fit=max&auto=format&n=GXlDUK5K0yNgB7O7&q=85&s=36bb4bfa914e58deb8fbde1eba1af343" width="225" height="225" data-path="images/model-icons/zai.png">
    ```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-2",
        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>

  <Accordion title="Qwen3-VL 30B" icon="https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/qwen.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=ceccb0e82dd42dae1af15f79d28fe557" width="225" height="225" data-path="images/model-icons/qwen.png">
    ```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="qwen3-vl-30b",
        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>

  <Accordion title="Llama 3.3 70B" icon="https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/llama.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=0e9748643c3987fbf26b9b7531745bc9" width="225" height="225" data-path="images/model-icons/llama.png">
    ```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>

  <Accordion title="GPT-OSS 120B" icon="https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/openai.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=1b9cbe9cd3cbfe37d282867e0d448c69" width="225" height="225" data-path="images/model-icons/openai.png">
    ```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)
    ```
  </Accordion>
</AccordionGroup>

### Audio Models

<AccordionGroup>
  <Accordion title="Voxtral Small 24B" icon="https://mintcdn.com/tinfoil/vfMAM73wcpT2SrpR/images/model-icons/mistral.png?fit=max&auto=format&n=vfMAM73wcpT2SrpR&q=85&s=c629064347c0c847d788dc2b2e0c1e10" width="225" height="225" data-path="images/model-icons/mistral.png">
    #### 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)
    ```
  </Accordion>
</AccordionGroup>

### Embedding Models

<AccordionGroup>
  <Accordion title="Nomic Embed Text" icon="https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/nomic.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=6568d64fd1a8b8110bf3354c1c8e78cd" width="318" height="225" data-path="images/model-icons/nomic.png">
    ```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])}")
    ```
  </Accordion>
</AccordionGroup>

## 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.