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

# Experimental emphasis

> Let a model decide which words to bold. Non-deterministic, opinionated, and the most fun endpoint in ACAAS.

`/v1/emphasize` is the only ACAAS endpoint that thinks for itself. Instead of
uppercasing every character, a small model reads your text and chooses which
words most deserve emphasis. Chosen words are wrapped in markdown bold
(`**word**`) and returned alongside the originals.

Because a model is in the loop, behavior is non-deterministic. Two identical
requests may produce different results, and the model may change between
versions. Treat this endpoint as a creative collaborator, not a pure function.

<Warning>
  Do not write code that depends on a specific emphasis output. If you need
  deterministic behavior, use [`/v1/shout`](/api-reference/shout) or
  [`/v1/scream`](/api-reference/scream).
</Warning>

## Make a request

The body takes a `text` field and an optional `emphasis_ratio`. Authentication
is the standard `X-API-Key` header.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.acaas.example.com/v1/emphasize \
    -H "X-API-Key: demo" \
    -H "Content-Type: application/json" \
    -d '{"text": "this is a quickstart guide", "emphasis_ratio": 0.4}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.acaas.example.com/v1/emphasize",
      headers={"X-API-Key": "demo"},
      json={
          "text": "this is a quickstart guide",
          "emphasis_ratio": 0.4,
      },
  )
  resp.raise_for_status()
  data = resp.json()
  print(data["result"])           # this is a **quickstart** **guide**
  print(data["emphasized_words"]) # ['quickstart', 'guide']
  ```

  ```javascript Node theme={"dark"}
  const resp = await fetch("https://api.acaas.example.com/v1/emphasize", {
    method: "POST",
    headers: {
      "X-API-Key": "demo",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "this is a quickstart guide",
      emphasis_ratio: 0.4,
    }),
  });

  if (!resp.ok) {
    throw new Error(`ACAAS request failed: ${resp.status}`);
  }

  const { result, emphasized_words } = await resp.json();
  console.log(result);            // "this is a **quickstart** **guide**"
  console.log(emphasized_words);  // ["quickstart", "guide"]
  ```
</CodeGroup>

## Tune `emphasis_ratio`

`emphasis_ratio` controls roughly what fraction of words the model selects.
Values above `0` and up to `1.0` are accepted. The default is `0.3`.

| Value           | Effect                                                     |
| --------------- | ---------------------------------------------------------- |
| `0.1`           | Sparse — only the single most important word in long text. |
| `0.3` (default) | Balanced — emphasizes a handful of key words.              |
| `0.6`           | Generous — most content words emphasized.                  |
| `1.0`           | Maximalist — nearly every word bolded. Defeats the point.  |

The ratio is a guideline, not a guarantee. The model rounds to whole words and
may pick fewer than requested for very short input.

## Response shape

```json theme={"dark"}
{
  "original": "this is a quickstart guide",
  "result": "this is a **quickstart** **guide**",
  "emphasized_words": ["quickstart", "guide"],
  "model": "acaas-emphasis-0.1",
  "experimental": true
}
```

* `original` — the text you sent in.
* `result` — the text with emphasized words wrapped in markdown bold.
* `emphasized_words` — the exact words the model chose, in order of appearance.
* `model` — name and version of the emphasis model. Pin against this if you
  need to detect upstream changes.
* `experimental` — always `true`. A reminder that behavior may shift.

## When to use it

Reach for `/v1/emphasize` when:

* You want highlights for human readers — release notes, headings, captions.
* The exact wording matters less than the rhythm of emphasis.
* You can render markdown bold downstream.

Avoid it when:

* You need byte-stable output across calls.
* You are formatting data for machines, not people.
* Markdown is not part of the rendering pipeline — bold asterisks will appear
  as literal characters.

## Errors

Validation errors return HTTP `422` with a `detail` array. The most common
causes are empty `text` or an `emphasis_ratio` outside the allowed range.

```json 422 example theme={"dark"}
{
  "detail": [
    {
      "loc": ["body", "emphasis_ratio"],
      "msg": "Input should be less than or equal to 1",
      "type": "less_than_equal"
    }
  ]
}
```

For the standard `401`, `413`, and `429` cases, see
[Quickstart → Handle errors](/quickstart#handle-errors).

## Next steps

<CardGroup cols={2}>
  <Card title="Full API reference" icon="book" href="/api-reference/emphasize">
    Complete request and response schema for `/v1/emphasize`.
  </Card>

  <Card title="Back to the basics" icon="megaphone" href="/api-reference/shout">
    The deterministic, predictable cousin: `/v1/shout`.
  </Card>
</CardGroup>