Skip to content

OpenAI plugin

The genkit-openai package provides the OpenAI plugin for OpenAI models: chat and reasoning models, embedders, image generation, text-to-speech, and transcription.

Terminal window
uv add genkit-openai

Import OpenAI and register it on Genkit:

from genkit import Genkit
from genkit_openai import OpenAI
ai = Genkit(plugins=[OpenAI()], model=OpenAI.gpt('gpt-5.5'))

OpenAI.gpt() returns a chat model ref bound to OpenAIConfig. A plain 'openai/gpt-5.5' string works too, and the model validates config against OpenAIConfig either way. The plugin registers a built-in catalog at startup; any other OpenAI model ID resolves on demand under the openai/ prefix.

Get an API key from the OpenAI Platform and provide it in one of these ways:

  • Environment variable: set OPENAI_API_KEY.
  • Plugin initialization: pass api_key. Other AsyncOpenAI settings, such as timeout, max_retries, organization, or project, go in client_options:
import os
from genkit_openai import OpenAI
OpenAI(
api_key=os.environ['OPENAI_API_KEY'],
client_options={'timeout': 30.0, 'max_retries': 3},
)
  • Per-request key: pass context={'secrets': {'api_key': tenant_key}} on generate() or generate_stream(). The call authenticates and bills as the tenant, and the plugin leaves its own organization and project off the request. The key never enters the request config, so it stays out of traces:
response = await ai.generate(
model=OpenAI.gpt('gpt-5.5'),
prompt='Summarize the open support tickets for this account.',
context={'secrets': {'api_key': tenant_key}},
)

With no key from any source, ai.generate() doesn’t raise; the response comes back with response.error.status set to FAILED_PRECONDITION. See Error types. Embedders always use the plugin’s key, since ai.embed() takes no context, so ai.embed() raises FAILED_PRECONDITION when the plugin has none.

To route through a proxy or gateway, pass base_url (up to and including /v1) or set OPENAI_BASE_URL.

from genkit import Genkit
from genkit_openai import OpenAI, OpenAIConfig
ai = Genkit(plugins=[OpenAI()])
@ai.flow()
async def summarize_ticket(ticket_body: str) -> str:
response = await ai.generate(
model=OpenAI.gpt('gpt-5.5'),
prompt=f'Summarize this customer issue in one sentence:\n\n{ticket_body}',
config=OpenAIConfig(
reasoning_effort='low',
max_output_tokens=256,
),
)
return response.text

OpenAIConfig uses Genkit’s standard max_output_tokens and stop_sequences names:

  • max_output_tokens goes out as max_completion_tokens for reasoning model IDs (gpt-5*, gpt-6*, o1, o3, o4) or when reasoning_effort is set, and as max_tokens otherwise.
  • stop_sequences goes out as stop.

Unknown top-level keys raise, including OpenAI’s raw max_tokens, max_completion_tokens, stop, and user, so a typo like temprature fails by name before the request is sent. For end-user abuse monitoring, set safety_identifier.

Pass output_schema and response.output comes back as an instance of that model. The plugin requests OpenAI Structured Outputs with strict: true. It rewrites the schema to meet strict mode’s rules: every object gets additionalProperties: false and every property becomes required, so a field with a default comes back as null rather than missing.

from pydantic import BaseModel
class MenuItem(BaseModel):
name: str
price_usd: float
allergens: list[str] | None = None
response = await ai.generate(
model=OpenAI.gpt('gpt-5.5'),
prompt='Invent a seasonal dish for a bistro menu.',
output_schema=MenuItem,
)
print(response.output.name)
# => Roasted Squash Risotto
from genkit import Genkit
from genkit_openai import OpenAI
ai = Genkit(plugins=[OpenAI()])
@ai.flow()
async def embed_flow(text: str) -> list[float]:
embeddings = await ai.embed(
embedder='openai/text-embedding-3-small',
content=text,
config={'dimensions': 512},
)
return embeddings[0].embedding

Pass tools in tools=[...] and control tool selection with tool_choice ('auto', 'required', or 'none'). The plugin sends each tool with strict: true and the same schema rewrite as structured output.

import httpx
from pydantic import BaseModel
from genkit import Genkit
from genkit_openai import OpenAI
ai = Genkit(plugins=[OpenAI()])
class WeatherRequest(BaseModel):
latitude: float
longitude: float
@ai.tool()
async def get_weather_tool(coordinates: WeatherRequest) -> float:
"""Get the current temperature for provided coordinates in Celsius."""
url = (
f'https://api.open-meteo.com/v1/forecast?'
f'latitude={coordinates.latitude}&longitude={coordinates.longitude}'
f'&current=temperature_2m'
)
async with httpx.AsyncClient() as client:
response = await client.get(url)
data = response.json()
return float(data['current']['temperature_2m'])
@ai.flow()
async def get_weather_flow(location: str) -> str:
response = await ai.generate(
model=OpenAI.gpt('gpt-5.4-mini'),
prompt=f"What's the weather like in {location} today?",
tools=[get_weather_tool],
tool_choice='auto',
)
return response.text
from genkit import FlowContext
@ai.flow()
async def summarize_stream(topic: str, ctx: FlowContext[str]) -> str:
result = ai.generate_stream(
model=OpenAI.gpt('gpt-5.5'),
prompt=f'Explain {topic} in three short paragraphs.',
)
async for chunk in result.stream:
ctx.send_chunk(chunk.text)
return (await result.response).text

The plugin asks OpenAI for usage on streamed responses, so the final response’s usage carries token counts.

Image, speech, and transcription models take string refs: OpenAI.gpt() accepts chat model IDs only and raises INVALID_ARGUMENT for the rest. Each model validates config against its own endpoint’s fields.

response = await ai.generate(
model='openai/gpt-image-1',
prompt='A watercolor illustration of a farmers market at dawn.',
config={'size': '1536x1024', 'quality': 'medium'},
)
print(response.media[0].url[:30])
# => data:image/png;base64,iVBORw0K
response = await ai.generate(
model='openai/gpt-4o-mini-tts',
prompt='Your table for four is ready.',
config={'voice': 'coral', 'instructions': 'Speak warmly and briefly.'},
)
print(response.media[0].content_type)
# => audio/mpeg

voice defaults to alloy. Set response_format to wav, opus, aac, flac, or pcm for formats other than MP3.

Send the audio as a base64 data: URI; the plugin does not download remote URLs.

import base64
from pathlib import Path
from genkit import Part
audio_b64 = base64.b64encode(Path('voicemail.mp3').read_bytes()).decode()
response = await ai.generate(
model='openai/gpt-4o-transcribe',
prompt=[Part.from_media(f'data:audio/mpeg;base64,{audio_b64}', content_type='audio/mpeg')],
)
print(response.text)
# => Hi, this is Dana calling about my reservation for Friday.

OpenAIConfig rejects unknown top-level keys. To forward newly added OpenAI API parameters before genkit-openai adds typed fields for them, pass them inside extra:

from genkit import Genkit
from genkit_openai import OpenAI, OpenAIConfig
ai = Genkit(plugins=[OpenAI()])
response = await ai.generate(
model='openai/gpt-5.5',
prompt='Draft a postmortem outline.',
config=OpenAIConfig(
seed=123,
extra={'custom_provider_flag': True},
),
)

The plugin sends extra as the OpenAI SDK’s extra_body, which replaces a top-level field of the same name. Genkit doesn’t check the values. Keys Genkit builds from the request (model, messages, tools, tool_choice, response_format, stream) are refused: the response comes back with response.error.status set to INVALID_ARGUMENT and nothing is sent. Pin a model snapshot with version instead of extra={'model': ...}.