# Word cloud generator

Make a word cloud picture from text or from a list of weighted words, with a choice of size and colours.

Counts the words, sizes each by its share, and packs them from the centre along a spiral. The result lists the words drawn with their counts.

- Endpoint: `POST https://setget.net/v1/tools/wordcloud` with JSON `{"input": {...}}` (add `"wait": 30` to hold the reply until the job finishes)
- MCP: `run_tool` with `slug` = `wordcloud`
- Page: https://setget.net/tools/wordcloud

## Files in, files out

This is a file tool. Its file inputs take file references, not file contents and not web addresses.

- Get a reference by uploading: `curl -T FILE https://setget.net/drop/` prints a line `ref  <id>/f1`. Or `POST https://setget.net/v1/drops` with `{"files":[{"name","size"}]}`, PUT the bytes to the returned `upload.url` with the listed headers, and use the file's `ref`. Over MCP use the `drop` tool. A file under about 700 KB can also be sent in place as a `data:<type>;base64,<content>` URI.
- Uploads are at most 100 MB per file, are readable by anyone with the link, and expire (one hour by default). Programs are refused.
- The tool runs as a job. The reply is `{"tool", "ms", "result", "files", "job"}`: `result` is JSON, and every result file comes back in `files` as `{"name", "size", "content_type", "kind", "url", "ref"}`. Download it from `url`, or pass `ref` as the input of another file tool.
- A job still running when the wait ends answers 202 with `job`. Follow it with `GET https://setget.net/v1/jobs/<id>?wait=30`, or stream progress from `GET https://setget.net/v1/jobs/<id>/events` (over MCP: the `job` tool). A person can watch it at `job.url`.

## Inputs

- `text` (optional, string): Text to count words in. The more often a word appears, the larger it is drawn.
- `words` (optional, json): Instead of text: an object that gives each word a weight, such as {"coffee": 12, "tea": 7}.
- `width` (optional, integer, default `800`, range 200..2400): Width of the picture in pixels.
- `height` (optional, integer, default `500`, range 200..2400): Height of the picture in pixels.
- `max_words` (optional, integer, default `100`, range 1..300): Draw at most this many words, starting with the most frequent.
- `palette` (optional, string, one of `bright`, `ocean`, `sunset`, `forest`, `berry`, `slate`, default `"bright"`): Colours for the words.
- `background` (optional, string, default `"#ffffff"`): Background colour: hex such as #ffffff, a basic colour name, or "transparent".
- `remove_stop_words` (optional, boolean, default `true`): Leave out very common English words such as "the", "and" and "with" when counting text.
- `min_length` (optional, integer, default `2`, range 1..20): When counting text, leave out words with fewer letters than this.
- `orientation` (optional, string, one of `mixed`, `horizontal`, default `"mixed"`): Mixed turns about one word in five on its side. Horizontal keeps every word level.
- `seed` (optional, integer, default `1`, range 0..1000000): Change this number to get a different arrangement of the same words.
- `format` (optional, string, one of `png`, `webp`, `jpg`, default `"png"`): Picture format.

## Example 1: Counted from a sentence

```json
{"input":{"text":"Tea is hot. Coffee is hot. Tea with milk, coffee with sugar, tea with lemon. Green tea, black tea, iced coffee, hot chocolate, warm milk, sweet honey, fresh lemon and mint tea.","width":600,"height":360},"wait":30}
```

## Example 2: Weighted words on a dark background

```json
{"input":{"words":{"python":30,"javascript":24,"rust":14,"go":12,"sql":18,"bash":9,"kotlin":6,"swift":7,"ruby":5,"java":16,"typescript":20,"c":8},"palette":"ocean","background":"#0f172a","width":640,"height":400,"orientation":"horizontal"},"wait":30}
```

**How is the size of a word chosen?** By how often it appears, or by the weight you give it. The most frequent word is the largest, and words are placed from the centre outwards so that none overlap.

**Will I get the same picture every time?** Yes. The same input and settings always give the same arrangement. Change "seed" for a different one.

**Why are some words missing?** Common English words are left out unless you turn "remove_stop_words" off, and the smallest words are dropped when the picture is full. The result lists every word that was drawn.

**Which alphabets work?** Latin letters with accents, Greek and Cyrillic. Text is split at spaces and punctuation, so languages written without spaces are not counted correctly.
