Services

Home Assistant services provided by Extended OpenAI Conversation for runtime configuration, vision queries, and skills management

Extended OpenAI Conversation registers four Home Assistant services you can call from automations, scripts, or Developer Tools → Services.

---

change_config

Dynamically update the integration’s connection settings — API key, Base URL, provider, and more — without restarting Home Assistant. The new values are validated against the API before being saved.

Parameters

Parameter	Required	Description
config_entry	✅	The Extended OpenAI Conversation config entry to update
api_key		New API key
base_url		New Base URL (e.g. http://localhost:11434/v1)
api_version		Azure API version (e.g. 2024-12-01-preview)
organization		OpenAI organization ID
skip_authentication		Skip auth verification — useful for local providers with no key
api_provider		openai or azure

At least one optional parameter must be provided. Calling the service with only config_entry does nothing.

If api_provider is set to azure, a custom base_url is required. The service raises an error if the Azure endpoint is missing.

Examples

Switch to Ollama

service: extended_openai_conversation.change_config
data:
  config_entry: YOUR_ENTRY_ID
  base_url: "http://192.168.1.100:11434/v1"
  api_key: "ollama"
  skip_authentication: true

service: extended_openai_conversation.change_config
data:
  config_entry: YOUR_ENTRY_ID
  base_url: "https://api.openai.com/v1"
  api_key: "sk-..."
  skip_authentication: false

service: extended_openai_conversation.change_config
data:
  config_entry: YOUR_ENTRY_ID
  api_provider: azure
  base_url: "https://yourname.cognitiveservices.azure.com/"
  api_key: "..."
  api_version: "2024-12-01-preview"

service: extended_openai_conversation.change_config
data:
  config_entry: YOUR_ENTRY_ID
  api_key: "sk-new-key..."

How to find config_entry

1. Go to Settings → Devices & Services
2. Click Extended OpenAI Conversation
3. The entry ID is in the browser URL: .../config/integrations/integration/extended_openai_conversation#ENTRY_ID

Alternatively, use the Developer Tools → Template panel:

{{ integration_entities('extended_openai_conversation') }}

Or call the service from Developer Tools → Services and use the config entry picker — no manual ID needed.

Behavior notes

• Validation first: The service connects to the API with the new credentials before saving. If the connection fails, the existing config is preserved and an error is raised.
• OpenAI default URL: Setting base_url to https://api.openai.com/v1 is treated as “no custom URL” — the integration uses OpenAI’s default endpoint, which is resilient to future URL changes by OpenAI.
• Partial updates: Only the fields you provide are changed. Unspecified fields keep their current values.

---

query_image

Send an image (local file or public URL) to a vision-capable model and get a text response back. The service returns the full API response object.

Parameters

Parameter	Required	Default	Description
config_entry	✅		Config entry to use for the API call
model	✅	gpt-4.1-mini	Vision-capable model name
prompt	✅		Question or instruction for the image
images	✅		List of image objects: [{url: "..."}]
max_tokens		300	Maximum tokens in the response

Examples

Public URL

service: extended_openai_conversation.query_image
data:
  config_entry: YOUR_ENTRY_ID
  model: gpt-4o-mini
  prompt: "What is in this image?"
  images:
    - url: "https://example.com/photo.jpg"

service: extended_openai_conversation.query_image
data:
  config_entry: YOUR_ENTRY_ID
  model: gpt-4o-mini
  prompt: "Describe what you see in the camera image."
  images:
    - url: "/config/www/camera_snapshot.jpg"

service: extended_openai_conversation.query_image
data:
  config_entry: YOUR_ENTRY_ID
  prompt: "Is there a person in this image? Reply yes or no."
  images:
    - url: "/config/www/front_door.jpg"
response_variable: vision_response

For local file paths, the path must be allowed in allowlist_external_dirs in your configuration.yaml.

homeassistant:
  allowlist_external_dirs:
    - /config/www

Return value

The service returns the full OpenAI chat completion response:

{
  "id": "chatcmpl-...",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The image shows a living room with a couch..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 85, "completion_tokens": 42 }
}

---

reload_skills

Reload all skills from the skills directory without restarting Home Assistant. Use this after manually adding or editing skill files.

Parameters

None.

Example

service: extended_openai_conversation.reload_skills

Return value

{ "loaded_skills": 3 }

The download_skill service automatically reloads skills after downloading, so a manual reload is only needed when you edit skill files directly.

See Managing Skills for details.

---

download_skill

Download a skill from the official GitHub repository and install it to your skills directory. Skills are reloaded automatically after download.

Parameters

Parameter	Required	Description
skill_name	✅	Name of the skill (e.g. crypto)

Example

service: extended_openai_conversation.download_skill
data:
  skill_name: crypto

Return value

{
  "skill_name": "crypto",
  "downloaded_files": ["skills/crypto/SKILL.md", "skills/crypto/crypto.py"],
  "target_directory": "/config/extended_openai_conversation/skills/crypto"
}

See Discover Skills for a list of available skills.