Skip to main content

Python SDK

Python SDK for Tinfoil’s secure AI inference API GitHub: tinfoil-python Build Status

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

import os
from tinfoil import TinfoilAI

# Configure client for DeepSeek V3.1 Terminus
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Multi-step agentic workflow
response = client.chat.completions.create(
    model="deepseek-v31-terminus",
    messages=[
        {
            "role": "user",
            "content": "Write a Python function to validate email addresses using regex, then test it with several examples and debug any issues."
        }
    ]
)

print(response.choices[0].message.content)
import os
from tinfoil import TinfoilAI

# Configure client for DeepSeek R1
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Complex reasoning task
response = client.chat.completions.create(
    model="deepseek-r1-0528",
    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)
import os
from tinfoil import TinfoilAI

# Configure client for Mistral Small 3.1 24B
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Multilingual conversation
response = client.chat.completions.create(
    model="mistral-small-3-1-24b",
    messages=[
        {
            "role": "user",
            "content": "Explain the concept of machine learning in both English and French."
        }
    ]
)

print(response.choices[0].message.content)
import os
from tinfoil import TinfoilAI

# Configure client for Llama 3.3 70B
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)
import os
from tinfoil import TinfoilAI

# Configure client for GPT-OSS 120B
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)
import os
from tinfoil import TinfoilAI

# Configure client for Qwen3 Coder 480B
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Repository-scale code understanding and agentic coding
response = client.chat.completions.create(
    model="qwen3-coder-480b",
    messages=[
        {
            "role": "user",
            "content": "Review this codebase and suggest architectural improvements for better modularity and testability."
        }
    ]
)

print(response.choices[0].message.content)
import os
from tinfoil import TinfoilAI

# Configure client for Qwen 2.5 72B
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Code generation and analysis
response = client.chat.completions.create(
    model="qwen2-5-72b",
    messages=[
        {
            "role": "user",
            "content": "Write a Python function to calculate the Fibonacci sequence up to n terms, then explain how it works."
        }
    ]
)

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

Audio Models

import os
from tinfoil import TinfoilAI

# Configure client for Whisper Large V3 Turbo
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="whisper-large-v3-turbo",
        language="en",  # Optional: specify language for better accuracy
        prompt="This is a business meeting discussing quarterly results"  # Optional: provide context
    )

print("Transcription:", transcription.text)
import os
from tinfoil import TinfoilAI

# Configure client for Kokoro TTS
client = TinfoilAI(
    api_key=os.getenv("TINFOIL_API_KEY")
)

# Example: Text-to-speech with different voices
text_to_speak = "Welcome to Tinfoil's secure AI platform. Your data remains private and protected."

# Single voice
response = client.audio.speech.create(
    model="kokoro",
    voice="af_sky",
    input=text_to_speak,
    response_format="mp3"
)
response.write_to_file("speech_single.mp3")

# Combined voices for richer sound
response = client.audio.speech.create(
    model="kokoro",
    voice="af_sky+af_bella",
    input=text_to_speak,
    response_format="mp3"
)
response.write_to_file("speech_combined.mp3")

print("Speech files generated successfully!")

Embedding Models

import os
from tinfoil import TinfoilAI
import numpy as np

# Configure client for Nomic Embed Text
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
    )
    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.

Guides