OpenAI

The OpenAI integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] adds conversation agents, AI tasks, speech-to-text, and text-to-speech powered by OpenAI to Home Assistant.

Controlling Home Assistant is done by providing the AI access to the Device control set of tools. You can control what devices and entities it can access from the exposed entities page. The AI can provide you information about your devices and control them.

This integration does not integrate with sentence triggers.

This integration requires an API key to use, which you can generate here.. This is a paid service, we advise you to monitor your costs in the OpenAI portal closely and configure usage limits to avoid unwanted costs associated with using the service.

Prerequisites

Important

This integration works only with the official OpenAI API endpoint and does not support OpenAI-API-compatible third-party services, proxies, or alternative backends. If you need support for other providers, consider using the OpenRouter integration as an alternative.

The OpenAI key is used to authenticate requests to the OpenAI API. To generate an API key take the following steps:

  • Log in to the OpenAI portal or sign up for an account.
  • Enable billing with a valid credit card
  • Configure usage limits.
  • Visit the API Keys page to retrieve the API key you’ll use to configure the integration.

Configuration

To add the OpenAI service to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

API key

API key from OpenAI for authentication.

To change the API key after setup, go to Settings > Devices & services, select the three dots menu on the OpenAI integration entry, then select Reconfigure.

Options

To define options for OpenAI, follow these steps:

  1. In Home Assistant, go to Settings > Devices & services.

  2. If multiple instances of OpenAI are configured, choose the instance you want to configure.

  3. On the card, select the cogwheel .

    • If the card does not have a cogwheel, the integration does not support options for this service.

    Screenshot showing the cogwheel icon on an integration card in the Settings > Devices & services page

  4. Edit the options, then select Submit to save the changes.

The integration provides the following types of services. Each type has its own button on the integration page, for example, Add conversation agent.

Conversation agents and AI tasks have the following configuration options. Some options are only available for one of them, or for some models.

Instructions

Instructions for the AI on how it should respond to your requests. It is written using Home Assistant Templating. Only available for conversation agents.

AI tools

Device control only accesses the entities you expose to voice assistants. Home Assistant accesses everything and only works for administrators, not voice assistant devices. Only available for conversation agents.

Recommended model settings

If enabled, the recommended model and settings are chosen. Enabled by default.

If you turn off Recommended model settings, you can configure the following options:

Model

The GPT language model is used for text generation. You can find more details on the available models in the ChatGPT Documentation. The default is “gpt-4o-mini”.

Maximum tokens to return in response

The maximum number of tokens that the AI model can generate in its response. The default is 3000. For more information, see the OpenAI Completion Documentation.

Temperature

A value that determines the level of creativity and risk-taking the model should use when generating text. A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results. Accepts values between 0 and 2. The default is 1. For gpt-5 and gpt-6 models, it only applies when Reasoning effort is set to None. See the OpenAI Completion Documentation for more information.

Top P

An alternative to temperature. Top P limits the model to the most likely words, whose probabilities add up to the Top P value. A lower Top P means the model only considers the most likely words. A higher Top P means it also considers less likely words. Accepts values between 0 and 1. The default is 1. For gpt-5 and gpt-6 models, it only applies when Reasoning effort is set to None. For more information, see the OpenAI Completion API Reference.

Store requests and responses in OpenAI

If enabled, OpenAI stores requests and responses and you can view them in your OpenAI dashboard logs. Disabled by default.

Service tier

The available service tiers are Auto, Standard, Flex, and Priority. Flex tier offers lower costs in exchange for slower response times, which can be useful for background automations. Priority processing delivers significantly lower and more consistent latency than the Standard tier at a higher price. Auto is the default value, which uses the project settings. See the Pricing for details on the supported models. When the selected tier is unavailable due to capacity or ramp rate limits, the request is processed at the Standard tier, and you are charged the Standard tier price.

Pro mode

Perform more model work to improve reliability on difficult tasks and return a single final answer. Enable it when quality matters more than latency and token usage. Pro mode aggregates the model work performed to produce the final answer and bills those tokens at the selected model’s standard token rates. Pro mode performs more model work than standard mode, increasing token usage and cost. This parameter is only applicable to GPT-5.6 and above; existing Pro model IDs keep their current behavior and pricing.

Enable web search

Enable the OpenAI-provided web search tool. Conversation and AI Task subentries offer this option for supported models. Web search and code interpreter can be enabled together for AI tasks, including tasks with structured output. Not available when the Reasoning effort option is set to Minimal.

Search context size

The search is performed with a separate fine-tuned model with its own context and its own pricing. This parameter controls how much context is retrieved from the web to help the tool formulate a response. The tokens used by the search tool do not affect the context window of the main model. These tokens are also not carried over from one turn to another — they’re simply used to formulate the tool response and then discarded. This parameter would affect the search quality, cost, and latency.

Include home location

This parameter allows using the location of your Home Assistant instance during search to provide more relevant search results.

Include links in web search results

If enabled, answers can include links to the web pages that the search used. If disabled, the model is asked not to include source citations. Disabled by default.

Enable code interpreter tool

Allows the model to run Python code to answer questions. Disabled by default. Not available for some models, for example, gpt-5-pro and the Codex models. Also not available when the Reasoning effort option is set to Minimal.

Reasoning effort

How much the model reasons before it answers. More reasoning can improve answers to difficult questions, but takes longer and uses more tokens. Only available for reasoning models, such as the o series, gpt-5, and gpt-6, but not for gpt-5-pro. The choices depend on the model, and include None, Minimal, Low, Medium, High, X-High, and Max. The default is Low.

Reasoning summary

How long and detailed the summaries of the model’s reasoning are. The choices are Off, Auto, Concise, and Detailed. Concise is not available for o series models. The default is Auto. Only available for reasoning models.

Image generation model

The model that the AI task uses to generate images. Only available for AI tasks, and only with models that support image generation. The default is gpt-image-2.5-flare.

Most of these options are in the second step of the dialog, Model-specific options. Which options appear depends on the model you selected.

The Speech-to-text (STT) subentries have the following configuration options:

Instructions

Instructions that can be used to improve the quality of the transcripts by giving the model additional context similarly to how you would prompt other LLMs. The model will try to match the style, language, and context of the prompt. You can also use it to pass a dictionary of the correct spellings of common misunderstood words. Check the OpenAI guide on prompting STT models for additional hints. Templates are not supported here.

Model

The Speech-to-text model for audio transcription. Select gpt-4o-transcribe, gpt-4o-mini-transcribe, or whisper-1, or enter the name of another model. The default is gpt-4o-mini-transcribe.

The Text-to-speech (TTS) subentries have the following configuration options:

Instructions

Instructions for the AI on how it should read your text. You can prompt the model to control aspects of speech, including accent, emotional range, intonation, impressions, speed of speech, tone, whispering, and more. Templates are not supported here.

Speed

Additionally adjust the speed of the generated speech. Accepts values between 0.25 and 4.0, where 1.0 is the default speed.

Text-to-speech always uses the gpt-4o-mini-tts model.

The AI task evaluation subentries have the following configuration options:

Model

The model that evaluates the AI task. The default is gpt-6-luna. You can also enter the name of another model.

Talking to Super Mario over the phone

You can use the OpenAI integration to talk to Super Mario and, if desired, have it control devices in your home.

Known limitations

  • Some older models are not supported, for example, o1-mini, o1-preview, and the realtime preview models. If you select one of them, Home Assistant shows This model is not supported, please select a different model.

Troubleshooting

OpenAI asks for the API key again

Symptom: “Reauthentication required. Please enter your updated API key.”

In Settings > Devices & services, OpenAI is listed under Attention required. When you select Reconfigure, the dialog shows the message “Reauthentication required. Please enter your updated API key.”

Description

OpenAI rejected the API key when Home Assistant started the integration. For example, this happens when the key was deleted in the OpenAI portal.

Resolution

  1. On the API Keys page, create a new API key.
  2. Go to Settings > Devices & services.
  3. Under Attention required, on the OpenAI card, select Reconfigure.
  4. Enter the new API key, and select Submit.
    • Result: The integration is set up again, and OpenAI is no longer listed under Attention required.
Repair issue: Organization verification required

Symptom: “Your organization must be verified to use this model.”

In Settings > System > Repairs, the repair issue Organization verification required appears. It appears when a conversation agent or AI task uses a model that needs a verified organization.

Description

OpenAI only allows verified organizations to use some models. The model that you selected is one of them. For details, refer to the OpenAI help article on organization verification.

Resolution

  1. In the OpenAI organization settings, select Verify Organization, and follow the steps.
  2. Wait up to 15 minutes. It can take that long until OpenAI gives you access to the model.
  3. Talk to the conversation agent again, or run the AI task again.
    • Result: The model answers. The repair issue stays in the list until Home Assistant restarts.
    • If you don’t want to verify your organization, select another model instead. To do so, on the OpenAI integration page, in the row of the conversation agent or AI task, select Reconfigure conversation agent or Reconfigure AI task .

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
    • Depending on the integration, the entries are listed under one of the following headings:
      • Devices
      • Hubs
      • Services
      • Integration entries
  3. To confirm, select Delete.
    • Home Assistant also deletes the devices and entities of the entry.
  4. If Home Assistant asks you to restart, restart Home Assistant.
  5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.