---
title: "A world document's own country as a greyscale heightmap."
method: POST
path: "/api/agents/run/world_heightmap"
tags: ["Production engines"]
---

# A world document's own country as a greyscale heightmap.

`POST /api/agents/run/world_heightmap`

## Request

- Base URL: `https://tomorrowlives.com`
- URL: `https://tomorrowlives.com/api/agents/run/world_heightmap`
- Auth: HTTP bearer

Draws the open country a world document generates (its worldgen block: seed, knobs, regions with their own relief, a ridge) as one greyscale PNG, row 0 north, so a world built with world_apply can be looked at before anyone walks it. area {w, h} makes a block of chunks from chunk (i, j) (w times h at most 25); range [lo, hi] fixes the grey scale in world units. The answer carries the height range, the grey scale used (greyFrom, greyTo, unitsPerGrey) and the name of the country each chunk sits in. A world with no worldgen block is bounded and is refused by name; set_worldgen opens it onto boundless country. Costs 1 unit.

## Request body

- object
  - `world` object, required: The world document, written inline as JSON. It needs a worldgen block to have country to draw.
  - `i` integer, required: The chunk column (east) to start from; chunks are 128 by 128 tiles.
  - `j` integer, required: The chunk row (south) to start from; chunks are 128 by 128 tiles.
  - `area` object: A block of chunks, w by h (each 1 to 25) from (i, j), drawn as one picture.
    - `w` integer, required
    - `h` integer, required
  - `range` unknown[]: Optional [lo, hi] in world units that fixes the grey scale, so separate calls tile on one scale.
    - unknown

## Response `200`

The job's result and files

- Job
  - `job` string
  - `verb` string
  - `units` integer
  - `ms` integer
  - `result` unknown
  - `files` object[]
    - `name` string
    - `bytes` integer
    - `content_type` string
    - `url` string
    - `url_expires_at` string, date-time

## Other responses

- `400`: The input is not valid
- `401`: No valid API key
- `402`: A pass or a payment is needed: a queued render on the free plan, a unit pack on the free plan (pass_required), a card plan's past-due renewal, or, on the free plan, an owner who has not confirmed their email yet (owner_unconfirmed; a pass needs no confirmation); or a payment did not go through (payment_failed, payment_token_unusable), and nothing was charged
- `403`: The account is suspended, the paying card is not from the United States (region_not_supported), or the address named as its owner said it is not theirs and costed runs are paused until a new owner is named (owner_removed)
- `413`: The input or the output is over its cap; a job stopped by the output cap is not charged
- `422`: The engine refused the input, a limit of the service's refused it (error: video_limit or pull_limit) or stopped the job, or the content policy refused the input (error: content_policy)
- `429`: A limit was hit; reset_at says when it lifts (also in Retry-After)
- `503`: The engines are busy or not installed
- `504`: The job ran past its time and was stopped

---

[API](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines.md) · [All operations](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/llms.txt) · [OpenAPI document](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/revisions/afc3d67322ac?raw)