# LLM chat

> Ask Anthropic, OpenAI or Gemini with your own vault key through the completion endpoint; text or JSON out.

Source: https://docs.tune.toys/nodes/ai.chat/

LLM chat sends a prompt to a language model with your own API key and sends the answer into the Patch as text or JSON.

## What it does

With `trigger` cabled, each trigger asks once; otherwise a new `prompt` does. The request goes to the Tune.Toys completion endpoint (`POST /v1/ai/complete`), which reads your key from the vault slot named after the provider (`anthropic`, `openai` or `gemini`) and calls the provider on the server. The key never reaches the browser or the Toy, and the platform's own key is never used for this node. Usage is billed to your key and shown on `usage` as tokens, model and provider.

The node's `system` field (up to 8 KiB) sets the instructions. `context` adds either a list of `{ role, content }` messages as conversation history or any JSON as extra context. With Format JSON the model is asked for one JSON value, which arrives parsed on `json`; `text` always carries the raw answer, and `bytes` carries a `data:` base64 payload if the answer contains one.

A Toy with LLM chat requires the network and the provider's vault slot; the Play surface shows a chip until both are ready. During [replay](https://docs.tune.toys/concepts/takes/) the model is not asked again: the recorded answers are played back, so a take plays without a key.

## When to use it

Use it to generate material: a melody as JSON for [Data to MIDI](https://docs.tune.toys/nodes/midi.from-data/), words for a display, settings from a description. Collect inputs with [Merge](https://docs.tune.toys/nodes/data.merge/) to give it context.

## Ports

<!-- ports:start -->

| Port      | Direction | Signal         | Lanes |
| --------- | --------- | -------------- | ----- |
| `prompt`  | Input     | Data (json)    | 1     |
| `trigger` | Input     | Data (trigger) | 1     |
| `context` | Input     | Data (json)    | 1     |
| `text`    | Output    | Data (string)  | 1     |
| `json`    | Output    | Data (json)    | 1     |
| `bytes`   | Output    | Data (bytes)   | 1     |
| `usage`   | Output    | Data (json)    | 1     |
| `error`   | Output    | Data (string)  | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter     | Label       | Range     | Default | Unit | Scale  | Notes                                                                                                         |
| ------------- | ----------- | --------- | ------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `provider`    | Provider    | 0 to 2    | 0       |      | linear | Model provider; its key comes from the vault slot of the same name. Choices: 0 Anthropic, 1 OpenAI, 2 Gemini. |
| `format`      | Format      | 0 to 1    | 0       |      | linear | Ask for plain text or a JSON value. Choices: 0 Text, 1 JSON.                                                  |
| `max_tokens`  | Max tokens  | 1 to 8192 | 1024    |      | linear | Longest response in tokens.                                                                                   |
| `temperature` | Temperature | 0 to 2    | 1       |      | linear | Higher values make answers more varied.                                                                       |

<!-- parameters:end -->

<!-- data:start -->

- `model`: text.
- `system`: text.

<!-- data:end -->

### Provider (`provider`)

Anthropic, OpenAI or Gemini. Its key comes from the vault slot of the same name. The node's `model` field picks a model; it defaults to the first model the addon manifest pins and accepts any other model id.

### Format (`format`)

Text, or JSON to ask for a single JSON value on `json`.

### Max tokens (`max_tokens`)

The longest answer, 1 to 8 192 tokens. Longer answers cost more.

### Temperature (`temperature`)

0 to 2. Low values give steadier answers; higher values more varied ones.

## Tips

- Ask for exactly the JSON shape you want, and test it with a [Console log](https://docs.tune.toys/nodes/log.console/) on `text` and `error`.
- Record a [take](https://docs.tune.toys/concepts/takes/) of a good answer: it replays anywhere without a key.

## See also

[Data to MIDI](https://docs.tune.toys/nodes/midi.from-data/), [Merge](https://docs.tune.toys/nodes/data.merge/), [Secrets and the vault](https://docs.tune.toys/concepts/secrets/), [Data cables](https://docs.tune.toys/concepts/data-cables/).