> ## Documentation Index
> Fetch the complete documentation index at: https://www.tryleap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Leap's API is at https://api.tryleap.ai. Send the key in the x-api-key header or as Authorization: Bearer; keys start with leap_.
> Take model IDs and input schemas from GET /v1/models/{creator}/{name}, or from https://api.tryleap.ai/v1/public/models without a key. Never guess an input field: unknown fields are a 400.
> Model inputs take uploaded file IDs (file_...), never URLs.
> To give a coding agent the whole API, install the Leap skill: curl -fsSL https://www.tryleap.ai/install.sh | sh
> To make media from ChatGPT, Claude or another MCP client without code, connect Leap's MCP server at https://app.tryleap.ai/api/mcp; see https://www.tryleap.ai/docs/mcp.
> The full OpenAPI 3.1 spec is at https://www.tryleap.ai/docs/openapi.json.

# Tools reference

> Every tool on Leap's MCP server: what it does, its inputs with their limits and defaults, what it returns, the scope it needs, whether it spends and how it's annotated.

Leap's MCP server has 13 tools. Each one answers twice: as JSON text the model reads, often followed by a sentence on what to do next, and as `structuredContent` that matches the tool's output schema. The tools that start, read or cancel runs also send thumbnails the model can look at, and links to the files.

When a call can't go ahead, the tool returns an error result (`isError: true`) with one line of text that says why and what to change. If one input is at fault, its name comes first:

```text wrap theme={"theme":"css-variables"}
workspace: You belong to several workspaces; pass workspace as one of: acme, jo-studio.
```

## At a glance

| Tool | What it does | Scope | Spends |
| - | - | - | - |
| [`search_models`](#search_models) | Finds models and presets by what they make | `workspace:read` | No |
| [`get_model`](#get_model) | One model's inputs and price | `workspace:read` | No |
| [`quote`](#quote) | Prices a run without starting it | `workspace:read` | No |
| [`plan`](#plan) | Turns the user's words into up to three priced options (beta) | `workspace:read` | No |
| [`generate`](#generate) | Runs a model or preset and waits for it | `media:generate` | Yes |
| [`generate_batch`](#generate_batch) | Runs up to 50 at once | `media:generate` | Yes |
| [`get_generation`](#get_generation) | Reads a run, and can wait for it | `workspace:read` | No |
| [`cancel_generation`](#cancel_generation) | Stops a run that hasn't finished | `media:generate` | No |
| [`upload_file`](#upload_file) | Stores a photo, video or sound for a model to use | `media:generate` | No |
| [`keep_output`](#keep_output) | Turns an image from a run into the next run's input | `media:generate` | No |
| [`list_generations`](#list_generations) | Lists the workspace's runs, newest first | `workspace:read` | No |
| [`get_account`](#get_account) | The balance and what's held | `workspace:read` | No |
| [`list_workspaces`](#list_workspaces) | The workspaces you belong to | `workspace:read` | No |

With an API key, `generations:read` stands in for `workspace:read` and `generations:write` for `media:generate` ([API keys](/docs/mcp/authentication#connect-with-an-api-key)). `generate`, `generate_batch`, `get_generation` and `list_generations` also draw their answer in ChatGPT and Claude ([Results in the chat](/docs/mcp#results-in-the-chat)).

### Annotations

Hosts read these hints to decide when to ask you first. ChatGPT asks before any tool that isn't read-only.

| Tools | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` |
| - | - | - | - | - |
| `search_models`, `get_model`, `quote`, `plan`, `get_generation`, `list_generations`, `get_account`, `list_workspaces` | `true` | `false` | not set | `false` |
| `generate`, `generate_batch`, `cancel_generation` | `false` | `true` | `true` | `false` |
| `upload_file` | `false` | `false` | `false` | `true` |
| `keep_output` | `false` | `false` | `true` | `false` |

`generate` and `generate_batch` are marked destructive because a charge can't be taken back once a run succeeds. They're idempotent because a retry with the same `idempotency_key` returns the first run. `upload_file` is the only tool that reaches outside Leap, to fetch a link.

### The `workspace` input

Every tool that reads or spends in a workspace takes `workspace`, an optional string: the workspace's slug. Leave it out if you belong to one workspace. With several, pass one, or the tool refuses and lists your slugs. A connection made with an API key works only in the key's workspace. See [Workspaces](/docs/mcp/authentication#workspaces).

## Shared shapes

### Generation

`generate`, `get_generation` and `cancel_generation` return one generation. `generate_batch` and `list_generations` return a list of them.

| Field | Type | Meaning |
| - | - | - |
| `id` | string | The run's ID, `gen_...`. |
| `model` | string | The model or preset it ran. |
| `status` | string | `queued`, `running`, `succeeded`, `failed` or `canceled`. |
| `cost_usd` | string or null | What it cost, as an exact decimal string in US dollars, once it succeeded. Null before, and for a run that didn't succeed. |
| `outputs` | array | One entry per file, empty until it succeeds: `url`, `content_type`, `width` and `height` (null for sound), and `poster_url` for a video, a JPEG of a frame from its middle. |
| `preview_url` | string | While a preset that makes a still first is running: that still. Absent otherwise. |
| `error` | string or null | Why a failed run failed, in words. |
| `failure_cause` | string or null | Why it failed, for the agent: `provider_error`, `provider_refused`, `photo_blocked`, `timeout`, `outage`, `input_removed` or `input_rejected`. See [When a run fails](/docs/mcp/runs#when-a-run-fails-or-is-refused). |
| `slow_at` | string | While a preset runs: from when it can be canceled whatever it has done. Absent otherwise. |
| `created_at` | string | When it started, in ISO 8601. |
| `studio_url` | string | The run's page in the studio, `https://app.tryleap.ai/<workspace>/runs/<id>`, with its result, receipt and downloads. |

Output links are signed and work for 24 hours. Reading the run again signs fresh ones.

### File

`upload_file` and `keep_output` return a file.

| Field | Type | Meaning |
| - | - | - |
| `id` | string | The file's ID, `file_...`. Put it in the model input that takes a file. |
| `content_type` | string | Read from the file's bytes, such as `image/jpeg` or `video/mp4`. |
| `bytes` | number | Its size. |
| `width`, `height` | number or null | For a picture or a video. |
| `duration_seconds` | number or null | For a video or a sound. |
| `filename` | string or null | The name kept with it. |
| `url` | string | A link to look at it, valid for 24 hours. Models take the `id`, never the link. |

## search\_models

Finds models and presets by what they make, with each one's price. The catalog is the same for every workspace, so this tool takes no `workspace`.

| Input | Type | Default | Notes |
| - | - | - | - |
| `query` | string | | Up to 200 characters, such as `vector logo`, `photoreal` or `cheap drafts`. Leave it out to list everything the filters allow. |
| `type` | string | | `model` or `preset`. |
| `modality` | string | | `image`, `video`, `audio`, `3d` or `text`. |
| `task` | string | | One task, such as `text-to-image`, `image-edit`, `image-to-video`, `text-to-speech`, `text-to-music`, `remove-background` or `speech-to-text`. [Models](/docs/models) lists them all. |
| `limit` | integer | 25 | 1 to 100. |

Returns `models`, best matches first. Each has `id`, `type`, `name`, `creator`, `modality`, `tasks`, `description`, `price` (such as `$0.033 per image`), `version` (a preset's version, or null), `status` (`preview`, `stable`, `deprecated` or `retired`), `sunset` and `replaced_by`.

Ask the way a person would, such as `transcribe a podcast` or `cheap fast logo`:

* A word that names a task ranks the models that do it first: "transcribe" finds speech-to-text models, "animate" image-to-video, and "upscale", "background", "lip sync" or "song" the models for those.
* A word that names a kind of output ranks that kind first: "photo", "logo" or "poster" for images, "clip" or "reel" for video, "voice", "podcast" or "song" for audio, "3D" for 3D.
* "Cheap", "budget" and "affordable" put the cheaper of equally good matches first. "Fast" also matches names with turbo, flash, schnell or lite.
* Any other word counts more in a model's ID or name than in its description. Words such as "make", "model" and "AI" are skipped, because every model would match them.

A preset shows once, at the version its bare ID runs, and a deprecated model comes after the one that replaces it.

## get\_model

One model's or preset's input schema and price: the fields `generate` accepts, their allowed values and defaults, and which inputs change the price.

| Input | Type | Notes |
| - | - | - |
| `model` | string, required | A model ID such as `black-forest-labs/flux-2-pro`, or a preset such as `leap/headshot@1`. |

Returns everything `search_models` returns for it, plus `revision`, `pricing` (as [Read a price](/docs/pricing#read-a-price) describes) and `input_schema`, the JSON Schema of its input. An input field that takes a file wants a file ID from `upload_file` or `keep_output`.

## quote

Checks an input and returns the exact price, without running anything or holding credit.

| Input | Type | Notes |
| - | - | - |
| `model` | string, required | As in `get_model`. |
| `input` | object, required | The model's input, as its `input_schema` describes it. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns `model`, `revision`, `input` with its defaults filled in, and `cost_usd`. An input that `generate` would refuse is refused here the same way, for free, naming the field (such as `input.aspect_ratio`) and what it accepts. A quote can't tell whether the model will accept a prompt.

## plan

Beta. Turns what the user asked for, in their own words, into what to run: up to three presets or models, each with the input the words filled in and its price. Nothing runs and nothing is charged.

| Input | Type | Notes |
| - | - | - |
| `ask` | string, required | The user's words as they wrote them, up to 20,000 characters, such as `me as a giant in Paris` or `cover for my single Low Tide`. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns `route`, `message`, `options` and `language`, the same answer as [`POST /v1/plans`](/docs/changelog). `route` says where the words lead:

| `route` | Meaning |
| - | - |
| `run` | One option fits. The agent reads its inputs with `get_model`, adds what's missing, such as a photo, then quotes and runs it. |
| `clarify` | Several fit. The agent shows you the options with their prices and lets you pick. |
| `refuse` | The words name a real person who hasn't agreed. Nothing runs, and `message` says why. |
| `free_tool` | You pasted writing. `message` points to Leap's free AI detector and humanizer. |
| `api` | You asked how to use Leap from code. |
| `link`, `empty`, `no_match` | A link, nothing, or nothing that matched. `message` says what to ask instead. |

Each option has `model`, `input`, `cost_usd` and `covered`, which is true when the workspace's welcome credit pays for it. A `cost_usd` of 0 means the price depends on a length the words didn't give, such as a voice-over's text, so quote the full input first.

## generate

Runs a model or preset and waits up to 50 seconds for the result. The price is held when it starts and charged only if it succeeds. The prompt and inputs go to the model's provider.

| Input | Type | Notes |
| - | - | - |
| `model` | string, required | As in `get_model`. |
| `input` | object, required | The model's input, as its `input_schema` describes it. |
| `idempotency_key` | string, required | A new string for each new request, such as a UUID: 1 to 255 printable ASCII characters. The same key returns the first run. See [Retrying](/docs/mcp/runs#retrying-without-paying-twice). |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns a [generation](#generation). A run still going after 50 seconds comes back `queued` or `running`: read it again with `get_generation`. A transcript comes as text inside `<untrusted-transcript>` tags ([Transcripts](/docs/mcp/runs#transcripts)).

Refuses before anything runs when the connection may not spend, when the balance doesn't cover the price (`Not enough credit.`, followed by where to add credits, or Leap's prices in ChatGPT and Codex), when an input doesn't fit the schema, and when a photo fails the photo check.

## generate\_batch

Runs up to 50 models or presets at once, such as four takes on a prompt or one prompt across several models, and waits up to 50 seconds for them. They're priced and held together, so either all start or none do. Each is charged only if it succeeds.

| Input | Type | Notes |
| - | - | - |
| `requests` | array, required | 1 to 50 items, each `{ "model": "...", "input": { ... } }`. |
| `idempotency_key` | string, required | A new string for each new batch. The same key returns the first batch. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns `id`, the batch's ID (`bat_...`), and `generations`, in the order of `requests`. The text says how many are still running, and shows the model the first picture of up to 8 runs that succeeded.

## get\_generation

Reads a run's status, cost and outputs, with thumbnails and fresh links. It can wait for a run that's still going.

| Input | Type | Notes |
| - | - | - |
| `id` | string, required | The run's ID, `gen_...`. |
| `wait` | integer | 1 to 50: seconds to wait for a running generation to finish. It answers as soon as the run ends. Leave it out to answer at once. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns a [generation](#generation). The result view calls this tool with `wait: 50` to show a video once it's ready.

## cancel\_generation

Stops a queued or running run. Its hold is released and nothing is charged.

| Input | Type | Notes |
| - | - | - |
| `id` | string, required | The run's ID, `gen_...`. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns the [generation](#generation), `canceled`. A run that already ended comes back as it is. A preset run that already has a `preview_url` can't be stopped until its `slow_at`, and neither can a run at a provider that bills it either way; both run to the end and are charged only if they succeed. See [Cancel](/docs/generations#cancel).

## upload\_file

Stores a photo, video or sound in the workspace so a model can take it, and returns its file ID. Pass exactly one of `url`, `data` or `file`.

| Input | Type | Notes |
| - | - | - |
| `url` | string | A public `https` link to the file, up to 2,048 characters. Leap follows up to 3 redirects and has 45 seconds to download it. |
| `data` | string | An image's bytes, base64-encoded, up to 4 MB once decoded. |
| `file` | object | A file the user attached in ChatGPT: `download_url` (required), `file_id` (required), `mime_type` and `file_name`. ChatGPT fills it in. |
| `filename` | string | 1 to 200 characters, a name to keep with the file. Without it, Leap keeps the attachment's name or the last part of the link. |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns a [file](#file). Images are PNG, JPEG or WebP up to 4 MB. Videos (MP4, MOV, WebM) and sounds (MP3, WAV, M4A) can be up to 100 MB, need some credit on the balance, and count toward the workspace's daily upload allowance. Uploading is free. A refusal names the input you sent (`url`, `file` or `data`), and a file that's none of those types gets `Send a PNG, JPEG or WebP image, an MP4, MOV or WebM video, or an MP3, WAV or M4A sound.` See [Give the agent a file](/docs/mcp/runs#give-the-agent-a-file).

## keep\_output

Turns an image a run made into a file ID, so the next run can start from it: animate it, edit it, or keep its character. Nothing is copied or charged, and the same output always gives the same ID.

| Input | Type | Default | Notes |
| - | - | - | - |
| `id` | string, required | | The run's ID, `gen_...`. |
| `index` | integer | 0 | Which output, from 0 to 15. |
| `workspace` | string | | See [the workspace input](#the-workspace-input). |

Returns a [file](#file). It works for the image outputs of a run that succeeded.

## list\_generations

The workspace's runs, newest first, with status, cost and output links.

| Input | Type | Default | Notes |
| - | - | - | - |
| `model` | string | | Only runs of this model or preset. |
| `status` | array | | Only runs in these states, such as `["queued", "running"]`. |
| `source` | array | | Only runs started from these: `studio`, `api`, `mcp`. |
| `limit` | integer | 10 | 1 to 50. |
| `cursor` | string | | The `next_cursor` of the previous page. |
| `workspace` | string | | See [the workspace input](#the-workspace-input). |

Returns `generations` and `next_cursor`, which is null on the last page. A cursor works only with the filters and workspace it came with. The list includes runs from the studio and the API too, unless `source` narrows it; there's no date filter, so to find yesterday's runs the agent pages back and reads `created_at`.

## get\_account

The workspace's balance, what running jobs hold, and where to add credits.

| Input | Type | Notes |
| - | - | - |
| `workspace` | string | See [the workspace input](#the-workspace-input). |

Returns `workspace` (`name` and `slug`), `balance_usd` (what's available to spend now, after holds), `held_usd` (what running jobs hold) and `add_credits_url`. That's the workspace's Credits page, or Leap's public price list in ChatGPT and Codex, whose rules don't allow checkout links.

## list\_workspaces

The workspaces you belong to. It takes no input.

Returns `workspaces`, each with `name`, `slug`, `url` (the workspace in the studio) and `role`, your role there, such as `owner`, `admin` or `member`, or `api_key` for a connection made with a key.

## Server details

| | |
| - | - |
| Name | `leap`, titled Leap |
| Transport | Streamable HTTP, stateless, at `https://app.tryleap.ai/api/mcp` |
| Instructions | Sent at initialization: find a model with `search_models` or `plan`, read its schema with `get_model`, check the price with `quote`, then `generate` with an `idempotency_key`. |
| Resource | `ui://leap/result-v1.html`, the result view, as an MCP App (`text/html;profile=mcp-app`). It loads media only from Leap's file hosts. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.