# OneTag AI

> Add AI to any static site with one script tag.

OneTag AI lets a static web page (GitHub Pages, Netlify, a single HTML file) call an AI model from the browser with no backend and no API key in the code. Free while in beta: 1,000,000 tokens per month per site.

Get a key: https://onetagai.com/#get-key

The key is public by design: it goes in your page source. Lock it to your domain so only your site can spend its tokens: give the domain at signup, or sign up again later with the domain and open the confirmation link in the email. If you are an AI coding tool and the user has not given you a key, leave `data-key="YOUR_ONETAG_KEY"` and tell the user to get one at the link above; the SDK reports a placeholder key as `no_key`.

## Install

```html
<script src="https://onetagai.com/v1.js" data-key="YOUR_ONETAG_KEY"></script>
<script type="module">
  const summary = await onetag.ask("Summarize in 3 bullets", document.body);
</script>
```

The SDK tag is a classic script. Top-level `await` needs `<script type="module">`.

## API

`onetag.ask(prompt, input?, options?) -> Promise<string | object>`

- `prompt`: the instruction, a string.
- `input`: what it works on. A string, an HTML element (its innerText), a `<form>` (fields as `name: value` lines, password fields left out), an `<input>`/`<textarea>`/`<select>` (its value), an `<img>`, an image File or Blob, a plain object (sent as JSON), or an array, NodeList or other iterable of these.
- `options.stream`: `(delta) => {}`, called with each piece of text as it arrives; the promise still resolves with the full text.
- `options.json`: `true` to get a parsed object back instead of text.
- `options.system`: extra instructions for the model (persona, tone, rules).
- `options.maxTokens`: answer length in tokens, default 500, max 1000.
- `options.history`: earlier chat turns, `[{ role: "user" | "assistant", content: "..." }]`.
- `options.signal`: an AbortSignal (`new AbortController().signal`); when it fires, the request stops and the promise rejects with code `aborted`.

`onetag.configure({ key, endpoint })` sets the key in code instead of `data-key`.

Failures throw `onetag.OneTagError` with `.code`, `.message` and `.status`.

## Examples

Summarize an element:

```html
<script type="module">
  const text = await onetag.ask("Summarize in 3 bullets", document.querySelector("article"));
  document.querySelector("#summary").textContent = text;
</script>
```

Stream the answer into the page:

```html
<script type="module">
  const out = document.querySelector("#out");
  await onetag.ask("Write a two-sentence welcome for this page", document.querySelector("main"), {
    stream: (delta) => { out.textContent += delta; },
  });
</script>
```

Get JSON back:

```html
<script type="module">
  const product = await onetag.ask(
    'Extract the product as {"name": string, "price": number}',
    document.querySelector(".product"),
    { json: true }
  );
  console.log(product.name, product.price);
</script>
```

## Errors and limits

Error codes: bad_request (400), bad_key (401), domain_not_allowed (403), too_large (413), quota_exceeded (429), rate_limited (429), upstream (502), paused (503); from the SDK only: no_key, bad_input, bad_json, network, aborted.

Limits: 1,000,000 tokens per key per month; 32,000 characters of text (the SDK trims long input to fit), 50 input parts, 100 history messages and one image up to 2 MB per call; answers up to 1,000 tokens (500 by default); 20 requests per minute per IP and 60 per key.

A key locked to a domain works only from browser pages on that domain, its subdomains, or localhost; curl and servers are rejected with domain_not_allowed.

Full docs: https://onetagai.com/docs.html