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:
At a glance
With an API key,
generations:read stands in for workspace:read and generations:write for media:generate (API keys). generate, generate_batch, get_generation and list_generations also draw their answer in ChatGPT and Claude (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.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.
Shared shapes
Generation
generate, get_generation and cancel_generation return one generation. generate_batch and list_generations return a list of them.
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.
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 noworkspace.
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.
get_model
One model’s or preset’s input schema and price: the fieldsgenerate accepts, their allowed values and defaults, and which inputs change the price.
Returns everything
search_models returns for it, plus revision, pricing (as 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.
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.
Returns
route, message, options and language, the same answer as POST /v1/plans. route says where the words lead:
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.
Returns a 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).
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.
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.
Returns a 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.
Returns the 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.
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 ofurl, data or file.
Returns a 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.
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.
Returns a 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.
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.
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. Returnsworkspaces, 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.