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

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

# Example: Multi-step agentic workflow
response = client.chat.completions.create(
    model="kimi-k2-thinking",
    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

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

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)

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)

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

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="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)

​
Embedding Models

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.

​
Guides

Web Search

Enable AI models to search the web with optional PII protection.

Tool Calling

Learn how to use function calling capabilities with AI models.

Structured Outputs

Use JSON schema validation for reliable data extraction.

Image Processing

Process images with multimodal AI models.

Document Processing

Upload and process documents securely.