> ## Documentation Index
> Fetch the complete documentation index at: https://extended-openai-conversation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`                                             |

<Note>
  At least one optional parameter must be provided. Calling the service with only `config_entry` does nothing.
</Note>

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

### Examples

<CodeGroup>
  ```yaml Switch to Ollama theme={null}
  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
  ```

  ```yaml Switch back to OpenAI theme={null}
  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
  ```

  ```yaml Switch to Azure OpenAI theme={null}
  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"
  ```

  ```yaml Change API key only theme={null}
  service: extended_openai_conversation.change_config
  data:
    config_entry: YOUR_ENTRY_ID
    api_key: "sk-new-key..."
  ```
</CodeGroup>

### 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:

```jinja theme={null}
{{ 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

<CodeGroup>
  ```yaml Public URL theme={null}
  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"
  ```

  ```yaml Local file theme={null}
  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"
  ```

  ```yaml In a script with response variable theme={null}
  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
  ```
</CodeGroup>

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

  ```yaml theme={null}
  homeassistant:
    allowlist_external_dirs:
      - /config/www
  ```
</Note>

### Return value

The service returns the full OpenAI chat completion response:

```json theme={null}
{
  "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

```yaml theme={null}
service: extended_openai_conversation.reload_skills
```

### Return value

```json theme={null}
{ "loaded_skills": 3 }
```

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

See [Managing Skills](/skills/discover-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

```yaml theme={null}
service: extended_openai_conversation.download_skill
data:
  skill_name: crypto
```

### Return value

```json theme={null}
{
  "skill_name": "crypto",
  "downloaded_files": ["skills/crypto/SKILL.md", "skills/crypto/crypto.py"],
  "target_directory": "/config/extended_openai_conversation/skills/crypto"
}
```

See [Discover Skills](/skills/discover-skills) for a list of available skills.