API

heic-convert

Runs in your own browser: we issue a work order, your agent opens the tool page and follows `recipe`, and the run settles when the converted file is saved. The photo never passes through our servers. Useful for iPhone photos, which arrive as HEIC and are rejected by most pipelines.

v1 beta browser · 5 tokens

Call it

POST https://timbrica.com/v1/tools/heic-convert/runs
Authorization: Bearer $TIMBRICA_KEY
Idempotency-Key: <your retry-safe key>
Content-Type: application/json

Input

Field	Type	Required	Notes
`format`	string	no	Output format, as the page selects it. one of: image/jpeg, image/png, image/webp default: image/jpeg

Input file

Your browser sets the file at the recipe's `upload` step. Do not stage it with /v1/uploads.
accepts: .heic, .heif

Browser recipe

This tool runs in your own browser. The work order you receive carries this recipe with the placeholders filled in; the selectors below are a versioned contract, not implementation detail — they do not change without a version bump.

{
    "engine": "dom",
    "steps": [
        {
            "action": "upload",
            "selector": "[data-tmb-api=\"input-file\"]",
            "accept": [
                ".heic",
                ".heif"
            ]
        },
        {
            "action": "select",
            "selector": "[data-tmb-api=\"format\"]",
            "value": "{{format}}"
        },
        {
            "action": "click",
            "selector": "[data-tmb-api=\"run\"]"
        },
        {
            "action": "wait",
            "selector": "[data-tmb-api=\"download\"]",
            "timeout_s": 120,
            "appears": "after_run"
        },
        {
            "action": "click",
            "selector": "[data-tmb-api=\"download\"]",
            "appears": "after_run"
        }
    ],
    "result": {
        "kind": "download",
        "settles": "automatically"
    }
}

What each action obliges you to do — recipes use nothing else:

`upload`	Put the input file into the file input matched by `selector` (it may be visually hidden: set it directly, e.g. Playwright setInputFiles). The file must match `accept`.
`click`	Click the element once it is visible AND enabled. A control that stays disabled means an earlier step did not take effect.
`fill`	Replace the value of a text input with `value`, firing input/change events as typing would.
`select`	Choose the option whose value is `value` in a <select>.
`wait`	Wait until the element is visible, up to `timeout_s` seconds (default 30).

Race every step against the work order's abort_when selector (html[data-tmb-run="failed"]). If it matches, the tool refused the job — for example a video that would not get any smaller. Stop, and GET the run: error.detail says why. Nothing is charged.

Errors it can return

validation_failed insufficient_tokens

History

v1 — 2026-07-30 — Initial release (browser lane).

This contract cannot change without a new version and a line above: a test compares the published schema, pricing and limits against a committed lockfile and fails the build otherwise. Subscribe to /v1/changelog to be told when something moves.