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.

Do not write code that depends on a specific emphasis output. If you need deterministic behavior, use /v1/shout or /v1/scream.

Make a request

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

cURL

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}'

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

{
  "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.

422 example

{
  "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.

Next steps

Full API reference

Complete request and response schema for /v1/emphasize.

Back to the basics

The deterministic, predictable cousin: /v1/shout.