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.
Installation
Section titled “Installation”uv add genkit-openaiConfiguration
Section titled “Configuration”Import OpenAI and register it on Genkit:
from genkit import Genkitfrom 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.
Authentication
Section titled “Authentication”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. OtherAsyncOpenAIsettings, such astimeout,max_retries,organization, orproject, go inclient_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}}ongenerate()orgenerate_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.
Chat models
Section titled “Chat models”from genkit import Genkitfrom 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.textOpenAIConfig uses Genkit’s standard max_output_tokens and stop_sequences names:
max_output_tokensgoes out asmax_completion_tokensfor reasoning model IDs (gpt-5*,gpt-6*,o1,o3,o4) or whenreasoning_effortis set, and asmax_tokensotherwise.stop_sequencesgoes out asstop.
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.
Structured output
Section titled “Structured output”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 RisottoText embedding models
Section titled “Text embedding models”from genkit import Genkitfrom 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].embeddingTool calling
Section titled “Tool calling”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 httpxfrom pydantic import BaseModel
from genkit import Genkitfrom 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'¤t=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.textStreaming
Section titled “Streaming”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).textThe plugin asks OpenAI for usage on streamed responses, so the final response’s usage carries token counts.
Image generation models
Section titled “Image generation models”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,iVBORw0KSpeech generation (text-to-speech)
Section titled “Speech generation (text-to-speech)”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/mpegvoice defaults to alloy. Set response_format to wav, opus, aac, flac, or pcm for formats other than MP3.
Transcription (speech-to-text)
Section titled “Transcription (speech-to-text)”Send the audio as a base64 data: URI; the plugin does not download remote URLs.
import base64from 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.Advanced usage
Section titled “Advanced usage”Forwarding undeclared fields with extra
Section titled “Forwarding undeclared fields with extra”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 Genkitfrom 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': ...}.