Skip to main content
POST
Create a generation

Authorizations

x-api-key
string
header
required

Your workspace API key, leap_.... Create one at https://app.tryleap.ai/go/api, and keep it on your server.

Headers

Idempotency-Key
string

A key you generate for this request, such as a UUID, so a retry never starts a second run. A retry with the same key and body returns the same generation as it is now, marked Idempotent-Replayed: true. The same key with a different body is a 409. A key belongs to your workspace and doesn't expire, so use a new one for each new request.

Required string length: 1 - 255
Pattern: ^[\x21-\x7e]+$
Example:

"7f1c2a9e-3b4d-4e8a-9c21-5d0f6a7b8c90"

Prefer
string

wait=N holds the request open for up to N seconds (at most 60) until the generation finishes, and Preference-Applied echoes the wait used. Most images finish inside the wait. If the run is still going when it ends, you get it back queued or running; poll it from there. Without this header the generation comes back queued at once.

Example:

"wait=60"

Body

application/json
model
string
required

The model or preset to run, such as black-forest-labs/flux-2-pro or leap/restore-photo@1. A preset ID without @N runs its latest version.

Maximum string length: 100
Pattern: ^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9.-]*(@[1-9][0-9]{0,3})?$
input
object

The model's input, as its input_schema from GET /v1/models/{creator}/{name} describes it. Fields you leave out take their defaults; unknown fields are refused. Files are file_... IDs.

webhook
string<uri>

An https URL to POST the generation.succeeded, generation.failed or generation.canceled event to when the run ends, signed with your workspace's default secret (GET /v1/webhooks/default/secret).

Maximum string length: 2048

Response

The generation: queued at once, or as it is when the wait ends.

One run of a model or preset, with its status, its outputs and what it cost.

id
string
required

The generation's ID, gen_ and 24 letters and digits.

object
string
required
Allowed value: "generation"
model
string
required

The model or preset it runs, with a preset's version.

modality
enum<string>
required

What it makes: image, video, audio, 3d or text.

Available options:
image,
video,
audio,
3d,
text
status
enum<string>
required

queued, then running, then one of succeeded, failed or canceled. Only succeeded is charged.

Available options:
queued,
running,
succeeded,
failed,
canceled
provider
string | null
required

Which upstream ran it, once one did. Informational: the model ID and input stay the same whichever runs it.

revision
string
required

The model's schema and price revision the run used.

Pattern: ^\d{4}-\d{2}-\d{2}$
input
object
required

The input as it runs, with the defaults filled in.

output
object[]
required
error
object | null
required

Why a failed run failed, such as a refused prompt or a provider error; null otherwise. A failed run isn't charged.

failure_cause
enum<string> | null
required

What made a failed run fail, for a program to branch on: provider_error, provider_refused (the model's safety filter said no), photo_blocked (the photo check refused the photo), timeout, outage (the provider had a declared incident or could not serve Leap), input_removed (an input file was gone) or input_rejected (the provider couldn't use an input file: too small, an unreadable format, or no face). Null for any other run, and for a failure from before causes were recorded.

Available options:
provider_error,
provider_refused,
photo_blocked,
timeout,
outage,
input_removed,
input_rejected
usage
object
required

What the run cost your workspace.

source
enum<string> | null
required

Where it was started: api, mcp or studio.

Available options:
studio,
api,
mcp
batch_id
string | null
required

The batch it belongs to, bat_...; null if none.

created_at
string<date-time>
required

When it was created.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
started_at
string<date-time> | null
required

When it started running; null while queued.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
completed_at
string<date-time> | null
required

When it reached a final status; null before.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
slow_at
string<date-time> | null
required

While a preset runs: when it counts as slow, one and a half times what Leap's runs of it take after started_at, scaled to this run's length, resolution and count. From then on a cancel works whatever the run has done, even once its preview shows. Null for any other run.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
deadline_at
string<date-time> | null
required

While a preset runs: when Leap stops it if it hasn't finished, three times what Leap's runs of it take after started_at, scaled to this run's length, resolution and count, between 5 minutes (2 for a picture) and 12. It then fails with the failure_cause timeout and costs nothing. Null for any other run.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
suggested_recipe
object | null
required

For a run of a model, not a recipe: the recipe made for what its words and files ask, when they clearly ask for one, such as two photos and "put the outfit from photo 2 on photo 1" on an image model (Virtual try-on), or a character sheet from a picture (Consistent character). Read from the words and files alone, so the same request always gets the same answer. Null when nothing matches clearly.

preview
object

While a preset that makes a still first is running: that still, once it exists, before the video it becomes. Absent for every other run, and for a run whose video also reads words or a photo you sent, such as a line to say or a photo the clip starts from: that still comes with the video. Also absent for the rest of a UTC day once 10 of the workspace's runs that showed one failed for their input.