How to beginner · 3 min read

How to use Instructor with Gemini

Q: How to use Instructor with Gemini

Use the instructor Python library with the OpenAI client configured for Gemini models by calling instructor.from_openai() and specifying the Gemini model like gemini-2.5-pro. Pass your Pydantic BaseModel as response_model to parse structured outputs from the chat completion.

Quick answer

Use the instructor Python library with the OpenAI client configured for Gemini models by calling instructor.from_openai() and specifying the Gemini model like gemini-2.5-pro. Pass your Pydantic BaseModel as response_model to parse structured outputs from the chat completion.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install openai>=1.0 instructor pydantic

Setup

Install the required packages and set your OpenAI API key in the environment.

Install packages: pip install openai instructor pydantic
Set environment variable: export OPENAI_API_KEY='your_api_key' (Linux/macOS) or setx OPENAI_API_KEY "your_api_key" (Windows)

bash

pip install openai instructor pydantic

Step by step

This example shows how to use instructor with the Gemini model gemini-2.5-pro to extract structured data from a user prompt using a Pydantic model.

python

import os
from openai import OpenAI
import instructor
from pydantic import BaseModel

# Initialize OpenAI client
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# Wrap OpenAI client with Instructor
instructor_client = instructor.from_openai(client)

# Define a Pydantic model for structured extraction
class UserInfo(BaseModel):
    name: str
    age: int

# Prepare messages
messages = [{"role": "user", "content": "Extract: Alice is 28 years old."}]

# Call chat completion with response_model and Gemini model
response = instructor_client.chat.completions.create(
    model="gemini-2.5-pro",
    response_model=UserInfo,
    messages=messages
)

# Access structured data
user_info = response
print(f"Name: {user_info.name}, Age: {user_info.age}")

output

Name: Alice, Age: 28

Common variations

Async usage: Use await instructor_client.chat.completions.acreate(...) in an async function.
Different Gemini models: Replace gemini-2.5-pro with other Gemini models like gemini-2.0-flash as needed.
Custom system prompt: Add a system parameter to guide the model's behavior.

python

import asyncio

async def async_example():
    response = await instructor_client.chat.completions.acreate(
        model="gemini-2.5-pro",
        response_model=UserInfo,
        messages=[{"role": "user", "content": "Extract: Bob is 35 years old."}]
    )
    print(f"Name: {response.name}, Age: {response.age}")

asyncio.run(async_example())

output

Name: Bob, Age: 35

Troubleshooting

If you get a ValidationError, ensure the model output matches the Pydantic schema exactly.
If the response is empty or incorrect, verify your messages format and that the model supports structured extraction.
Check your OPENAI_API_KEY environment variable is set correctly.

✅

Key Takeaways

Use instructor.from_openai() to wrap the OpenAI client for Gemini integration.
Pass a Pydantic BaseModel as response_model to parse structured outputs.
Specify the Gemini model like gemini-2.5-pro in the model parameter.
Async calls are supported with acreate() for non-blocking usage.
Validate your schema and environment variables to avoid common errors.

Verified 2026-04 · gemini-2.5-pro

Verify ↗