OpenAI plugin

The @genkit-ai/compat-oai package includes a pre-configured plugin for official OpenAI models.

Installation

npm install @genkit-ai/compat-oai

Configuration

To use this plugin, import openAI and specify it when you initialize Genkit:

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

export const ai = genkit({
  plugins: [openAI()],
});

The plugin requires an API key for the OpenAI API. You can get one from the OpenAI Platform.

Configure the plugin to use your API key by doing one of the following:

Set the OPENAI_API_KEY environment variable to your API key.
Specify the API key when you initialize the plugin:

openAI({ apiKey: yourKey });

However, don’t embed your API key directly in code! Use this feature only in conjunction with a service like Google Cloud Secret Manager or similar.

Usage

The plugin provides helpers to reference supported models and embedders.

Chat Models

You can reference chat models like gpt-6-astra, gpt-5.6-sol, gpt-5.5, and gpt-5.4-mini using the openAI.model() helper.

import { genkit, z } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

const ai = genkit({
  plugins: [openAI()],
});

export const jokeFlow = ai.defineFlow(
  {
    name: 'jokeFlow',
    inputSchema: z.object({ subject: z.string() }),
    outputSchema: z.object({ joke: z.string() }),
  },
  async ({ subject }) => {
    const llmResponse = await ai.generate({
      prompt: `tell me a joke about ${subject}`,
      model: openAI.model('gpt-5.5'),
    });
    return { joke: llmResponse.text };
  },
);

You can also pass model-specific configuration:

const llmResponse = await ai.generate({
  prompt: `tell me a joke about ${subject}`,
  model: openAI.model('gpt-5.5'),
  config: {
    temperature: 0.7,
  },
});

Strict structured output

Set strict: true to have OpenAI enforce your output schema exactly, through Structured Outputs. It maps to response_format.json_schema.strict and requires JSON output with a schema:

const { output } = await ai.generate({
  model: openAI.model('gpt-5.5'),
  prompt: 'Invent a character for a fantasy novel.',
  output: {
    format: 'json',
    schema: z.object({ name: z.string(), backstory: z.string() }).strict(),
  },
  config: { strict: true },
});

OpenAI’s strict mode requires additionalProperties: false on every object, and Genkit does not add it for you, so apply .strict() to every object in the schema. Strict mode also requires every property to be required, and Genkit passes the schema through unchanged, so use .nullable() instead of .optional() for fields that may have no value. Without a JSON output schema, strict: true fails with INVALID_ARGUMENT.

Image Generation Models

The plugin supports image generation models like gpt-image-2.

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

const ai = genkit({
  plugins: [openAI()],
});

// Reference an image generation model
const gptImage = openAI.model('gpt-image-2');

// Use it to generate an image
const imageResponse = await ai.generate({
  model: gptImage,
  prompt: 'A photorealistic image of a cat programming a computer.',
});

const imageUrl = imageResponse.media?.url;

Text Embedding Models

You can use text embedding models to create vector embeddings from text.

import { genkit, z } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

const ai = genkit({
  plugins: [openAI()],
});

export const embedFlow = ai.defineFlow(
  {
    name: 'embedFlow',
    inputSchema: z.object({ text: z.string() }),
    outputSchema: z.object({ embedding: z.string() }),
  },
  async ({ text }) => {
    const embedding = await ai.embed({
      embedder: openAI.embedder('text-embedding-3-small'),
      content: text,
    });

    return { embedding: JSON.stringify(embedding) };
  },
);

Audio Transcription and Speech Models

The OpenAI plugin also supports audio models for transcription (speech-to-text) and speech generation (text-to-speech).

Transcription (Speech-to-Text)

Use models like gpt-transcribe to transcribe audio files.

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';
import * as fs from 'fs';

const ai = genkit({
  plugins: [openAI()],
});

const transcriber = openAI.model('gpt-transcribe');
const audioFile = fs.readFileSync('path/to/your/audio.mp3');

const transcription = await ai.generate({
  model: transcriber,
  prompt: [
    {
      media: {
        contentType: 'audio/mp3',
        url: `data:audio/mp3;base64,${audioFile.toString('base64')}`,
      },
    },
  ],
});

console.log(transcription.text);

Speech Generation (Text-to-Speech)

Use models like tts-1 to generate speech from text. OpenAI has deprecated its text-to-speech models, including tts-1, and shuts them down on January 6, 2027.

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';
import * as fs from 'fs';

const ai = genkit({
  plugins: [openAI()],
});

const tts = openAI.model('tts-1');
const speechResponse = await ai.generate({
  model: tts,
  prompt: 'Hello, world! This is a test of text-to-speech.',
  config: {
    voice: 'alloy',
  },
});

const audioData = speechResponse.media;
if (audioData) {
  fs.writeFileSync(
    'output.mp3',
    Buffer.from(audioData.url.split(',')[1], 'base64'),
  );
}

Advanced usage

Passthrough configuration

You can pass configuration options that are not defined in the plugin’s custom configuration schema. This permits you to access new models and features without having to update your Genkit version.

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

const ai = genkit({
  plugins: [openAI()],
});

const llmResponse = await ai.generate({
  prompt: `Tell me a cool story`,
  model: openAI.model('gpt-4-new'), // hypothetical new model
  config: {
    seed: 123,
    new_feature_parameter: ... // hypothetical config needed for new model
  },
});

Genkit passes this config as-is to the OpenAI API giving you access to the new model features. Note that the field name and types are not validated by Genkit and should match the OpenAI API specification to work.

Web-search built-in tool

Some OpenAI models support web search. You can enable it in the config block:

import { genkit } from 'genkit';
import { openAI } from '@genkit-ai/compat-oai/openai';

const ai = genkit({
  plugins: [openAI()],
});

const llmResponse = await ai.generate({
  prompt: `What was a positive news story from today?`,
  model: openAI.model('gpt-5.5'),
  config: {
    web_search_options: {},
  },
});