Python - Tinfoil Documentation

View on GitHub

tinfoilsh/tinfoil-python

Overview

The Tinfoil Python SDK is a wrapper around the OpenAI Python client 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

pip install tinfoil

Migration from OpenAI

Migrating from OpenAI to Tinfoil is straightforward:

# 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

https://mintcdn.com/tinfoil/GXlDUK5K0yNgB7O7/images/model-icons/zai.png?fit=max&auto=format&n=GXlDUK5K0yNgB7O7&q=85&s=36bb4bfa914e58deb8fbde1eba1af343

GLM-5.2

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)

https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/qwen.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=ceccb0e82dd42dae1af15f79d28fe557

Qwen3-VL 30B

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)

https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/llama.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=0e9748643c3987fbf26b9b7531745bc9

Llama 3.3 70B

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)

https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/openai.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=1b9cbe9cd3cbfe37d282867e0d448c69

GPT-OSS 120B

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)

Kimi K2.5

import os
from tinfoil import TinfoilAI

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

# Example: Native multimodal agentic coding
response = client.chat.completions.create(
    model="kimi-k2-5",
    messages=[
        {
            "role": "user",
            "content": "Review this codebase and suggest architectural improvements for better modularity and testability."
        }
    ]
)

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

Audio Models

https://mintcdn.com/tinfoil/vfMAM73wcpT2SrpR/images/model-icons/mistral.png?fit=max&auto=format&n=vfMAM73wcpT2SrpR&q=85&s=c629064347c0c847d788dc2b2e0c1e10

Voxtral Small 24B

Transcription

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

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

https://mintcdn.com/tinfoil/7kpqELCdP4WIVCil/images/model-icons/nomic.png?fit=max&auto=format&n=7kpqELCdP4WIVCil&q=85&s=6568d64fd1a8b8110bf3354c1c8e78cd

Nomic Embed Text

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:

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 that can be used with Tinfoil. All methods and types are identical. See the OpenAI Python client documentation for complete API usage and documentation.

View on GitHub

​Overview

​Installation

​Migration from OpenAI

​Model Examples

​Chat Models

​Audio Models

​Transcription

​Audio Q&A

​Embedding Models

​Async Usage

​API Documentation