Skip to content
Layer Docs

Execute inference

Viewing v2— current version

POST
/v2/workspaces/{workspace_id}/inferences
curl --request POST \
  --url https://api.app.layer.ai/api/v2/workspaces/:workspace_id/inferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "base_model_id": "<string>",
  "reference_sets": [],
  "modality": "text",
  "prompt": "<string>",
  "negative_prompt": "<string>",
  "width": 0,
  "height": 0,
  "auto_aspect_ratio": true,
  "auto_resolution": "<string>",
  "batch_size": 4,
  "num_inference_steps": 0,
  "guidance_scale": 0,
  "prompt_strength": 0,
  "quality": "low",
  "sharpness": 0,
  "prompt_enhancement": "off",
  "duration_seconds": 0,
  "generate_audio": true,
  "keep_audio": true,
  "draft": true,
  "instrumental": true,
  "loop": true,
  "output_format": "mp3",
  "lyrics": "<string>",
  "composition_plan": {
    "positive_styles": [],
    "negative_styles": [],
    "sections": [
      {
        "name": null,
        "duration_seconds": null,
        "positive_styles": null,
        "negative_styles": null,
        "lines": null
      }
    ],
    "respect_section_durations": true
  },
  "fps": 0,
  "video_effects": [],
  "use_ta_pose": true,
  "pose_mode": "A_POSE",
  "include_textures": true,
  "detailed_geometry": true,
  "remesh_geometry": true,
  "texture_resolution": "RES_2K",
  "remove_lighting": true,
  "mesh_density": "ULTRA",
  "preserve_uvs": true,
  "segment_by": "AUTO",
  "segment_part_names": [
    "<string>"
  ],
  "quad_mesh": true,
  "pbr_materials": true,
  "low_poly": true,
  "generate_parts": true,
  "face_limit": 0,
  "enable_rigging": true,
  "enable_animation": true,
  "stability": 0,
  "use_speaker_boost": true,
  "similarity_boost": 0,
  "style_exaggeration": 0,
  "speed": 0,
  "upscale_ratio": 0,
  "creativity": 0,
  "resemblance": 0,
  "denoise": 0,
  "compression_repair": 0,
  "halo_reduction": 0,
  "recover_detail": 0,
  "detail": 0,
  "grain": 0,
  "refine_strength": 0,
  "realism": 0,
  "face_enhancement": true,
  "face_enhancement_strength": 0,
  "face_enhancement_creativity": 0,
  "target_region": "all",
  "color_preservation": true,
  "vectorize": true,
  "vectorization_mode": "spline",
  "vectorization_color_mode": "color",
  "vectorization_layering": "stacked",
  "vectorization_filter_speckle": 0,
  "vectorization_color_precision": 0,
  "vectorization_layer_difference": 0,
  "vectorization_corner_threshold": 0,
  "vectorization_length_threshold": 0,
  "vectorization_splice_threshold": 0,
  "vectorization_max_iterations": 0,
  "vectorization_path_precision": 0,
  "transparency": true,
  "reframe": true,
  "tileability": true,
  "projection": "EQUIRECTANGULAR",
  "projection_strength": 0,
  "refill": true,
  "camera_transform": {
    "distance_delta": 0,
    "rotation_delta": {
      "pitch_delta": null,
      "yaw_delta": null,
      "roll_delta": null
    },
    "zoom_delta": {
      "fov_y_delta": null
    }
  },
  "camera_trajectory": [
    {
      "time": 0,
      "azimuth": 0,
      "elevation": 0,
      "distance": 0
    }
  ],
  "scene_lighting": {
    "lights": []
  },
  "tile_grid": {
    "shape": "SQUARE",
    "orientation": "DIAMOND",
    "elevation": 0,
    "facing": 0,
    "footprint_width": 1,
    "footprint_depth": 1,
    "height": 0,
    "tile_width": 128,
    "light_from": "left"
  },
  "output_fit": {
    "trim": false,
    "canvas": "CONTENT",
    "width": 0,
    "height": 0,
    "scale": "PLACE",
    "anchor": "TOP_LEFT",
    "padding": 0
  },
  "nine_slice": true,
  "color_palette": {
    "colors": [],
    "reference_set_id": "<uuid>"
  },
  "expression": "<string>",
  "target_language": "<string>",
  "audio_sections": [],
  "audio_extension": {
    "before_seconds": 0,
    "after_seconds": 0
  },
  "video_section": {
    "start_seconds": 0,
    "end_seconds": 0
  },
  "guidance_files": [],
  "seed": -1,
  "mask": {
    "file_id": "<uuid>",
    "for_transparency": true,
    "for_nontransparency": true,
    "edge_radius": 0
  },
  "session_name": "<string>",
  "session_id": "<uuid>",
  "webhook": {
    "url": "<string>",
    "events": [
      "inference.completed"
    ],
    "metadata": {}
  }
}'

Changed in v2. This endpoint’s contract differs from v1. See the v2 migration guide for the request and response changes before you switch.

Start an AI inference (image, video, 3D, or audio). Pass a base_model_id, at least one entry in reference_sets, or both — with reference sets alone a compatible base model is picked from them. Returns immediately with an ID. Poll with GET /v2/workspaces/{workspace_id}/inferences/{inference_id} for results. Creative Units are not checked here: an underfunded workspace is still accepted and the run then reports FAILED with error_code INSUFFICIENT_BALANCE. Use the estimate endpoint’s has_sufficient_creative_units to check before submitting.

Reference-set errors: REFERENCE_SET_NOT_FOUND (404 — unknown, deleted, or outside this workspace’s reach), NO_COMPATIBLE_MODEL (422 — no enabled base model can apply these sets), REFERENCE_SET_REQUIRED (422 — the chosen model needs an applicable set), REFERENCE_SET_CONFLICT (422 — two sets supply the same singular adapter), REFERENCE_SET_LIMIT_EXCEEDED (422: more sets of one kind than the model takes, e.g. a second ANIMATION set on a 3D animating model), and INPUT_FILE_REQUIRED (422 — the sets select an edit-only model with no asset to edit).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspace_id
required
Workspace Id

Id of the workspace that owns the resource.

string format: uuid

Id of the workspace that owns the resource.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
<= 255 characters

Opaque key making a retry of this request return the first result. A 2xx response is replayed for 24 hours with Idempotent-Replayed: true. A 4xx releases the key. A 5xx, or a request still running, holds the key for 120 seconds, during which a retry gets 409; after that a retry executes again. The key covers the method, path, query, and byte-identical body it was first used with; reusing it for a different request is rejected with 422. Protection is best effort: if the key store is unavailable, or a record is lost early, a retry can execute again even after an earlier 409. See the Idempotency section of the API description.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
ExecuteInferenceV2Request

REST request body for executing an inference. workspace_id comes from path.

object
base_model_id
Base Model Id

Base model to run, as an id (e.g. flux-dev), display name, or community alias.

string
nullable
reference_sets
Reference Sets

Reference sets to apply, up to 10.

Array<object>
default: <= 10 items
InferenceReferenceSetInput
object
set_id
required
Set Id

Reference set ID from GET /v2/workspaces/{workspace_id}/reference-sets.

string format: uuid
weight
Weight

Weight for the set’s LoRA adapter when one applies. Ignored for sets applied as reference images or prompt text.

number
default: 1 <= 2
modality
Any of:
Modality
string
Allowed values: text image audio video three_d playable world
prompt
Prompt

Text prompt.

string
nullable <= 100000 characters
negative_prompt
Negative Prompt

What to steer the output away from. Honored by the models whose inference-schema lists negative_prompt, and ignored by the rest.

string
nullable <= 100000 characters
width
Width

Output width in pixels. If not specified, a default resolution based on the model will be applied.

integer
nullable > 0
height
Height

Output height in pixels. If not specified, a default resolution based on the model will be applied.

integer
nullable > 0
auto_aspect_ratio
Auto Aspect Ratio

Derive the output’s shape from the input instead of from width/height. Only on models whose capabilities include autoAspectRatio.

boolean
nullable
auto_resolution
Auto Resolution

The size tier of an auto_aspect_ratio run (e.g. ‘2K’), one of the model’s autoResolutions. Unset, the size follows the input.

string
nullable
batch_size
Batch Size

Number of outputs (1-16).

integer
default: 4 >= 1 <= 16
num_inference_steps
Num Inference Steps

Number of diffusion steps.

integer
nullable > 0
guidance_scale
Guidance Scale

Guidance scale (CFG).

number
nullable
prompt_strength
Prompt Strength

How closely the generated audio follows the text prompt (0-1); higher means less variation. Honored by ElevenLabs Sound Effects and the Sonilo video-to-music models, and ignored by every other model. To control how closely an image or video generation follows an input image, set guidance_files[].weight instead.

number
nullable <= 1
quality
Quality

Quality level: low, medium, or high.

string
nullable
Allowed values: low medium high
sharpness
Sharpness

Output sharpness.

number
nullable
prompt_enhancement
Any of:
PromptEnhancement

How much effort the provider spends rewriting the prompt before it generates.

One ladder for a dial providers spell a dozen ways: an on/off flag (enable_prompt_expansion, prompt_optimizer, enhance_prompt, expand_prompt, autoprompt, …) or a mode (MiniMax’s disabled/fast/balanced/quality, Seedream’s fast/standard, Qwen’s none/quality). Member order is the ladder. Each model declares the levels it offers as prompt_enhancement_levels, and the provider mapping spells a level its own way; an on/off provider offers OFF and STANDARD.

This is the provider’s own rewriting, distinct from Layer’s prompt-enhance action, which rewrites the prompt visibly before the request is made.

string
Allowed values: off fast standard quality
duration_seconds
Duration Seconds

Output length in seconds — a video clip’s duration, or the clip length for audio models whose capabilities report duration_seconds_min and duration_seconds_max. A value outside a model’s supported range is refused.

number
nullable > 0
generate_audio
Generate Audio

Generate audio with video.

boolean
nullable
keep_audio
Keep Audio

Keep audio from input video.

boolean
nullable
draft
Draft

Render a quick, low-cost draft instead of the full-quality output, on models whose capabilities report draft. Complete the draft later with the model named by the generating model’s draftCompletionModelId, passing the draft file as a DRAFT_VIDEO input (DRAFT_WORLD for a world, DRAFT_MESH for a mesh).

boolean
nullable
instrumental
Instrumental

Guarantee a track with no vocals, on models whose capabilities report instrumental. Asking for one in the prompt is only a suggestion.

boolean
nullable
loop
Loop

Compose the clip to repeat with no audible seam, on models whose capabilities report loop.

boolean
nullable
output_format
Any of:
AudioOutputFormat

Container for a delivered audio file.

Providers name these their own way and Layer never re-encodes what one returns, so the format a caller asks for is only keepable on models whose capabilities list it. Members are named for their wire value: the frontend artifacts preserve enum names, and a name that differed from the value would hand clients a format string the request API rejects.

string
Allowed values: mp3 wav aac flac
lyrics
Lyrics

Words to be sung, for models whose capabilities report lyrics. A separate input from the prompt, which describes the music itself.

string
nullable
composition_plan
Any of:
CompositionPlan

A track authored as an ordered list of sections rather than as one description.

The split is load-bearing: the plan’s own styles carry what must hold for the whole track, genre, era, production character, palette, and each section carries only what changes. Reversing it produces a track that either drifts or never moves.

A plan replaces the prompt rather than supplementing it. Providers taking a plan ignore the prompt, the requested length and the vocal-free flag, because the plan already states all three.

object
positive_styles
Positive Styles
Array<string>
default:
negative_styles
Negative Styles
Array<string>
default:
sections
required
Sections
Array<object>
>= 1 items <= 30 items
MusicSection

One section of a planned track, carrying its own length, styles and sung lines.

positive_styles/negative_styles are the section’s delta: what enters or leaves here, against the palette the plan holds for the whole track. A section’s exclusions are what keep it empty of something the rest of the track has, the plan-wide negatives cannot express “no percussion until the second section”.

object
name
required
Name
string
>= 1 characters <= 100 characters
duration_seconds
required
Duration Seconds
number
>= 3 <= 120
positive_styles
Positive Styles
Array<string>
default:
negative_styles
Negative Styles
Array<string>
default:
lines
Lines
Array<string>
default:
respect_section_durations
Respect Section Durations
boolean
default: true
fps
Fps

FPS for LTX video generation (e.g. 25 or 50).

integer
nullable > 0
video_effects
Video Effects

Video effects to apply.

Array<object>
default:
ForgeVideoEffectInput
object
type
required
VideoEffectType

Video effect type. See model capabilities for supported effects per model.

string
Allowed values: general orbit_360 action_run agent_reveal arc arc_left baseball_kick basketball_dunks boxing buckle_up building_explosion bullet_time car_chasing car_explosion car_grip catch catwalk crane_down crane_over_the_head crane_up crash_zoom_in crash_zoom_out dirty_lens disintegration dolly_in dolly_left dolly_out dolly_right dolly_zoom_in dolly_zoom_out double_dolly downhill_pov dutch_angle eyes_in face_punch fisheye flying focus_change fpv_drone glam handheld head_tracking hyperlapse invisible jib_down jib_up kiss lazy_susan lens_crack lens_flare levitation low_shutter melting moonwalk_left moonwalk_right mouth_in object_pov overhead push_to_glass rap_flex robo_arm set_on_fire skateboard_glide skateboarding skateboard_kickflip skateboard_ollie skate_cruise ski_carving ski_powder snorricam snowboard_carving snowboard_powder soul_jump static super_dolly_in super_dolly_out tentacles through_object_in through_object_out thunder_god tilt_down tilt_up timelapse_human timelapse_landscape turning_metal whip_pan wiggle wind_to_face yoyo_zoom zoom_in zoom_out
weight
Weight

Effect strength (0-100).

number
nullable <= 100
use_ta_pose
Use Ta Pose

Deprecated: use pose_mode. Legacy rig-ready-pose toggle for 3D.

boolean
nullable
pose_mode
Any of:
PoseMode

Canonical rest pose a character-mesh model is asked to generate in. A_POSE places the arms angled down at roughly 45°; T_POSE holds them straight out to the sides. Only meaningful for models that advertise the pose_modes capability (e.g. Meshy V7).

Deliberately a light top-level module (like base_model_id), NOT under pkg.models.inference: the Blueprint definition layer registers this as a BlueprintType and migrates legacy node ports, and must do so without pulling in the heavy pkg.models.inference package, which would perturb the Temporal workflow-sandbox import graph and split pydantic class identity.

string
Allowed values: A_POSE T_POSE
include_textures
Include Textures

Include textures in 3D output.

boolean
nullable
detailed_geometry
Detailed Geometry

Denser, more detailed geometry (Meshy V7 ultra mode). Costs extra; support varies by model.

boolean
nullable
remesh_geometry
Remesh Geometry

Set false to skip the provider’s remesh phase and keep its raw geometry. Support varies by model.

boolean
nullable
texture_resolution
Any of:
TextureResolution

Edge length of a generated mesh’s base color texture.

Offered where the model’s texture_resolutions capability lists it (Meshy’s own API).

string
Allowed values: RES_2K RES_4K RES_8K
remove_lighting
Remove Lighting

Strip baked highlights and shadows from the texture. Support varies by model.

boolean
nullable
mesh_density
Any of:
MeshDensity

How many faces a mesh keeps, as a level the provider sizes adaptively.

Stands in for a fixed face limit where the model’s mesh_densities capability offers it.

string
Allowed values: ULTRA HIGH MEDIUM LOW
preserve_uvs
Preserve Uvs

Keep the mesh’s own UV layout when retexturing. Support varies by model.

boolean
nullable
segment_by
Any of:
SegmentBy

What a mesh is split along.

AUTO finds the parts itself; PARTS cuts along the parts segment_part_names names. Offered where the model’s segment_by capability lists it.

string
Allowed values: AUTO PARTS
segment_part_names
Segment Part Names

Parts to split along when segment_by is PARTS, at most 10.

Array<string>
nullable <= 10 items
quad_mesh
Quad Mesh

Generate quad mesh.

boolean
nullable
pbr_materials
Pbr Materials

Generate PBR materials.

boolean
nullable
low_poly
Low Poly

Generate low-poly mesh.

boolean
nullable
generate_parts
Generate Parts

Generate separate parts.

boolean
nullable
face_limit
Face Limit

Face/polygon limit for 3D mesh.

integer
nullable > 0
enable_rigging
Enable Rigging

Rig the generated 3D mesh with a skeleton. Honored by the models whose capabilities report rigging.

boolean
nullable
enable_animation
Enable Animation

Animate the generated 3D mesh with the motion of the animation reference set passed in reference_sets (category animation), or the provider’s default motion without one; implies rigging. Honored by the models whose capabilities report animation.

boolean
nullable
stability
Stability

Audio stability (0-1).

number
nullable <= 1
use_speaker_boost
Use Speaker Boost

Boost speaker clarity.

boolean
nullable
similarity_boost
Similarity Boost

Voice similarity boost (0-1).

number
nullable <= 1
style_exaggeration
Style Exaggeration

Style exaggeration (0-1).

number
nullable <= 1
speed
Speed

Speech speed multiplier.

number
nullable > 0
upscale_ratio
Upscale Ratio

Upscale factor (e.g. 2.0, 4.0).

number
nullable
creativity
Creativity

Creative variation strength for upscaling.

number
nullable
resemblance
Resemblance

Resemblance to original for upscaling.

number
nullable
denoise
Denoise

Noise removal. On the models whose capabilities report denoise_range, in that range; a value outside it is refused.

number
nullable
compression_repair
Compression Repair

Compression-artifact removal. On the models whose capabilities report compression_repair_range, in that range; a value outside it is refused.

number
nullable
halo_reduction
Halo Reduction

Removal of bright edge outlines. On the models whose capabilities report halo_reduction_range, in that range; a value outside it is refused.

number
nullable
recover_detail
Recover Detail

How much of the source’s own detail is kept. On the models whose capabilities report recover_detail_range, in that range; a value outside it is refused.

number
nullable
detail
Detail

How much fine detail the model adds. On the models whose capabilities report detail_range, in that range; a value outside it is refused.

number
nullable
grain
Grain

Film grain laid over the result. On the models whose capabilities report grain_range, in that range; a value outside it is refused.

number
nullable
refine_strength
Refine Strength

How strongly lettering and shapes are rebuilt. On the models whose capabilities report refine_strength_range, in that range; a value outside it is refused.

number
nullable
realism
Realism

Bias of added detail toward photorealism. On the models whose capabilities report realism_range, in that range; a value outside it is refused.

number
nullable
face_enhancement
Face Enhancement

Set false to skip the face-restoration pass, on models whose capabilities report face_enhancement.

boolean
nullable
face_enhancement_strength
Face Enhancement Strength

Strength of the face pass. On the models whose capabilities report face_enhancement_strength_range, in that range; a value outside it is refused.

number
nullable
face_enhancement_creativity
Face Enhancement Creativity

Facial detail the face pass invents. On the models whose capabilities report face_enhancement_creativity_range, in that range; a value outside it is refused.

number
nullable
target_region
Any of:
TargetRegion
string
Allowed values: all subject background
color_preservation
Color Preservation

Keep the source’s palette, on models whose capabilities report color_preservation.

boolean
nullable
vectorize
Vectorize

Vectorize the output image.

boolean
nullable
vectorization_mode
Any of:
VectorizationMode
string
Allowed values: spline polygon
vectorization_color_mode
Any of:
VectorizationColorMode
string
Allowed values: color binary
vectorization_layering
Any of:
VectorizationLayering
string
Allowed values: stacked cutout
vectorization_filter_speckle
Vectorization Filter Speckle

Drop specks smaller than this many pixels. Honored by the models whose capabilities report vectorization_controls.

integer
nullable <= 20
vectorization_color_precision
Vectorization Color Precision

Color quantization level; lower merges more colors. Honored by the models whose capabilities report vectorization_controls.

integer
nullable >= 1 <= 10
vectorization_layer_difference
Vectorization Layer Difference

Color difference that splits gradient layers. Honored by the models whose capabilities report vectorization_controls.

integer
nullable >= 1 <= 32
vectorization_corner_threshold
Vectorization Corner Threshold

Minimum angle, in degrees, kept as a sharp corner (spline mode). Honored by the models whose capabilities report vectorization_controls.

integer
nullable <= 180
vectorization_length_threshold
Vectorization Length Threshold

Longest curve segment before it is subdivided (spline mode). Honored by the models whose capabilities report vectorization_controls.

number
nullable <= 10
vectorization_splice_threshold
Vectorization Splice Threshold

Angle, in degrees, at which a curve is split (spline mode). Honored by the models whose capabilities report vectorization_controls.

integer
nullable <= 90
vectorization_max_iterations
Vectorization Max Iterations

Curve-fitting passes. Honored by the models whose capabilities report vectorization_controls.

integer
nullable >= 1 <= 20
vectorization_path_precision
Vectorization Path Precision

Decimal places kept in SVG path coordinates. Honored by the models whose capabilities report vectorization_controls.

integer
nullable >= 1 <= 10
transparency
Transparency

Put the output on a transparent background. Also accepted as remove_background.

boolean
nullable
reframe
Reframe

Reframe/extend the image.

boolean
nullable
tileability
Tileability

Generate a seamless texture that tiles without a visible edge. Honored by the models whose inference-schema lists tileability (list them with GET .../base-models?tileable=true), and ignored by the rest.

boolean
nullable
projection
Any of:
ImageProjection

The geometry an output image is drawn in, when it is not an ordinary flat picture.

string
Allowed values: EQUIRECTANGULAR
projection_strength
Projection Strength

How strongly a model’s 360 LoRA draws the projection, as its scale. Unset takes the LoRA’s own.

number
nullable <= 2
refill
Refill

Outpaint/refill transparent areas.

boolean
nullable
camera_transform
Any of:
CameraTransformDelta

Relative adjustments to apply to an existing origin-locked orbit camera state.

object
distance_delta
Distance Delta
number
nullable
rotation_delta
Any of:
CameraRotationDelta
object
pitch_delta
Pitch Delta
number
nullable
yaw_delta
Yaw Delta
number
nullable
roll_delta
Roll Delta
number
nullable
zoom_delta
Any of:
CameraZoomDelta
object
fov_y_delta
Fov Y Delta
number
nullable
camera_trajectory
Camera Trajectory

A camera path for an image-to-video run: 2 to 12 keyframes, each an orbit pose (azimuth and elevation in degrees, distance where 1 is the source image’s framing) at a time from 0 (first frame) to 1 (last). Honored by the models whose capabilities report camera_trajectory.

Array<object>
nullable >= 2 items <= 12 items
CameraTrajectoryKeyframe

One orbit-camera pose at a normalized point in a generated clip.

object
time
required
Time
number
<= 1
azimuth
required
Azimuth
number
elevation
required
Elevation
number
>= -90 <= 90
distance
required
Distance
number
> 0
scene_lighting
Any of:
SceneLightingConfig

An array of orbiting light sources to populate the graphics engine environment.

object
lights
Lights
Array<object>
default:
OrbitLight
object
id
required
Id
string
distance
required
Distance
number
>= 0.0001
rotation
required
OrbitLightRotation
object
pitch
required
Pitch
number
>= -90 <= 90
yaw
required
Yaw
number
>= -360 <= 360
properties
required
OrbitLightProperties
object
intensity
required
Intensity
number
color_hex
required
Color Hex
string
/^#([A-Fa-f0-9]{6})$/
cast_shadows
Cast Shadows
boolean
nullable
tile_grid
Any of:
TileGrid

One tile’s place on the grid. Every tile of a set shares all but the footprint and height.

object
shape
TileShape

The outline of one cell of the grid, seen from straight above.

string
default: SQUARE
Allowed values: SQUARE HEXAGON
orientation
Any of:
TileOrientation

How a cell’s outline is turned to the camera.

A square cell is either DIAMOND, turned 45 degrees so its base reads as a diamond (the isometric look), or ALIGNED with the camera, as top-down maps are. A hexagon has either a vertex (POINTY_TOP) or an edge (FLAT_TOP) at the top.

string
Allowed values: DIAMOND ALIGNED POINTY_TOP FLAT_TOP
elevation
Elevation

Unset takes 30 (2:1 dimetric) for a square, 60 for a hexagon.

number
nullable >= 20 <= 90
facing
TileFacing

A quarter turn of the camera around a diamond tile, in degrees clockwise seen from above.

0 is the facing a set is drawn in first; the others show the same subject’s other sides. A hexagon is only drawn facing 0.

integer
0
Allowed values: 0 90 180 270
footprint_width
Footprint Width
integer
default: 1 >= 1 <= 8
footprint_depth
Footprint Depth
integer
default: 1 >= 1 <= 8
height
Height
number
0 <= 6
tile_width
Tile Width
integer
default: 128 >= 16 <= 1024
light_from
TileLightSide

The side the key light comes from, seen from the camera.

string
default: left
Allowed values: left right
output_fit
Any of:
OutputFit
object
trim
Trim
boolean
canvas
OutputFitCanvas
string
default: CONTENT
Allowed values: CONTENT FIXED
width
Width
integer
nullable >= 1 <= 4096
height
Height
integer
nullable >= 1 <= 4096
scale
OutputFitScale

How the drawing goes onto a fixed canvas. The names follow the workflow Resize node’s.

string
default: PLACE
Allowed values: PLACE SHRINK_AND_PAD FIT_AND_PAD FIT_AND_CROP STRETCH
anchor
OutputFitAnchor

The point of the drawing that lands on the same point of the canvas.

BASE is a game tile’s base: its anchor, the bottom centre of the cell it stands on, lands at the bottom centre of the canvas, so tiles of one grid stand on the same point whatever rises above them.

string
default: CENTER
Allowed values: TOP_LEFT TOP_CENTER TOP_RIGHT CENTER_LEFT CENTER CENTER_RIGHT BOTTOM_LEFT BOTTOM_CENTER BOTTOM_RIGHT BASE
padding
Padding
integer
0 <= 512
nine_slice
Nine Slice

Deliver the image as a 9-slice UI element (a button, frame or panel that stretches): after everything else the run does, the plain band through its middle is found on each axis, the stretched regions are cleaned so nothing smears, and the insets are recorded as the file’s nineSlice metadata. An image with no such band is delivered as drawn, without insets. Image outputs only.

boolean
nullable
color_palette
Any of:
InferenceColorPalette

The colors a generation is asked to use, and the reference set they were picked from.

The run uses the colors it carries: a later edit to the set changes no run already made. reference_set_id only names where they came from, so a form can show and restore it.

object
colors
Colors
Array<object>
default: <= 16 items
PaletteColor

One named color of a palette.

object
name
required
Name
string
>= 1 characters <= 64 characters
hex
required
Hex
string
/^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})$/
role
Role
string
nullable <= 64 characters
reference_set_id
Reference Set Id
string format: uuid
nullable
expression
Expression

The expression a face edit gives the face, one of the names the model’s capabilities list under expressions.

string
nullable
target_language
Target Language

The language a dub speaks, as one of the ISO 639-1 codes the model’s capabilities list under dub_languages.

string
nullable
audio_sections
Audio Sections

Regenerate stretches of the init audio: each section is a window from start_seconds to end_seconds, measured from the clip’s anchor (its start by default), that the prompt rewrites while the rest is kept. Honored by the audio models listed for the inpainting use case.

Array<object>
default:
AudioEditSection

An interior time window of the source clip to regenerate (inpaint).

Times are non-negative magnitudes measured from anchor. The window is always inside the clip; extending past the clip is outpainting (see [[AudioExtension]]), a separate operation.

object
start_seconds
required
Start Seconds
number
end_seconds
required
End Seconds
number
anchor
AudioAnchor

Which boundary of the source clip a section’s times are measured from.

string
default: START
Allowed values: START END
audio_extension
Any of:
AudioExtension

Outpaint: how much audio to add before/after the source clip.

object
before_seconds
Before Seconds
number
0
after_seconds
After Seconds
number
0
video_section
Any of:
VideoSection

A time window of the source clip, in seconds from its start, that an edit replaces.

A video insert cuts the source at start_seconds, plays a generated scene, then picks the source back up at end_seconds.

object
start_seconds
required
Start Seconds
number
end_seconds
required
End Seconds
number
guidance_files
Guidance Files

Reference images/files to guide generation.

Array<object>
default: <= 20 items
ForgeGuidanceFileInput
object
file_id
required
File Id

File ID of an uploaded file.

string format: uuid
type
required
GuidanceFileType

Guidance type. See model capabilities for supported types per model.

string
Allowed values: init_image reference_image scribble color_sketch pose depth canny softedge_hed segmentation lineart face ip_adapter first_frame last_frame init_video reference_video draft_video init_mesh texture_image draft_mesh element_frontal_image element_reference_image element_video draft_world init_audio reference_audio
weight
Weight

Influence weight (0-1). Defaults to 0.5 for init, 1 for others.

number
nullable <= 1
view
Any of:
MultiViewSlot

The view a source image shows, for 3D models that read their sources by view.

string
Allowed values: FRONT LEFT BACK RIGHT
seed
Seed

Random seed. -1 for random.

integer
default: -1
mask
Any of:
ForgeMaskInput
object
file_id
File Id

Mask image file ID.

string format: uuid
nullable
for_transparency
For Transparency

Use the init image’s transparent areas as the mask. As the only mask source, a fully opaque init used as stored (no transform, padding or target) is refused; a mask file works on any init.

boolean
nullable
for_nontransparency
For Nontransparency

Use non-transparent areas as mask.

boolean
nullable
edge_radius
Edge Radius

Mask edge blur radius in pixels.

integer
0
session_name
Session Name

Organize this run under the most recent active session with this name, creating one if none matches. Ignored when session_id is given.

string
nullable <= 255 characters
session_id
Session Id

Organize this run under this session, from GET /v2/workspaces/{workspace_id}/sessions. Takes precedence over session_name, and must belong to this workspace.

string format: uuid
nullable
webhook
Any of:
WebhookInput

Where to POST this request’s terminal events, and what to include with them.

object
url
required
Url

HTTPS URL that receives a POST when this request reaches a terminal state. Must be publicly reachable; must not redirect. Acknowledge with any 2xx within 10 seconds and do the work asynchronously. Reply 410 to stop delivery permanently.

string
<= 2048 characters
events
Events

Narrows what is delivered. Omit to receive every event this request can produce, which is what expected_events on the response lists.

Array<string>
nullable
Allowed values: inference.completed inference.failed inference.cancelled training.succeeded training.failed scoring_run.completed scoring_run.failed workflow_run.succeeded workflow_run.failed workflow_run.cancelled
metadata
Metadata

Opaque key/value pairs echoed back verbatim in every delivery, for correlating a callback with your own records. At most 10 keys and 1024 bytes in total.

object
key
additional properties
string

Responses

Section titled “Responses”

202

Section titled “202”

Successful Response

Media typeapplication/json
ExecuteInferenceV2Output
object
inference_id
required
Inference Id

Unique identifier for this inference run.

string format: uuid
status
required
InferenceStatus

Current status: IN_PROGRESS.

string
Allowed values: in_progress complete failed cancelled deleted
estimated_price_creative_units
Estimated Price Creative Units

Estimated price in Creative Units.

number
nullable
poll_interval_seconds
required
Poll Interval Seconds

Suggested polling interval in seconds.

integer
created_at
required
Created At

Timestamp of when the run was created.

string format: date-time
session_id
Session Id

Session ID the run was added to, if a session was specified.

string format: uuid
nullable
normalized_parameters
Any of:
NormalizedInferenceParametersV2

Inference parameters after model-specific normalization.

These reflect the actual values used for generation, including model defaults applied for any parameters not explicitly set.

object
width
Width

Resolved output width in pixels.

integer
nullable
height
Height

Resolved output height in pixels.

integer
nullable
batch_size
Batch Size

Number of outputs to generate.

integer
nullable
num_inference_steps
Num Inference Steps

Resolved number of diffusion steps.

integer
nullable
guidance_scale
Guidance Scale

Resolved guidance scale.

number
nullable
duration_seconds
Duration Seconds

Resolved output length in seconds — video duration or audio clip length.

number
nullable
fps
Fps

Resolved FPS.

integer
nullable
base_model_id
required
Base Model Id

Base model used for the run, resolved or auto-picked.

string
reference_set_contributions
Reference Set Contributions

Per-set summary of what each reference set contributed.

Array<object>
default:
ForgeReferenceSetContribution
object
set_id
Set Id

Reference Set ID this contribution belongs to, if any.

string format: uuid
nullable
lora_applied
Lora Applied

True when a LoRA finetune was applied for this set.

boolean
animation_applied
Animation Applied

True when an animation (Meshy rigging action) finetune was applied for this set.

boolean
voice_applied
Voice Applied

True when a voice (ElevenLabs) finetune was applied for this set.

boolean
mapped_asset_count
Mapped Asset Count

Number of assets successfully mapped to guidance inputs.

integer
0
palette_applied
Palette Applied

True when the set’s color palette was appended to the prompt.

boolean
prompt_fallback_applied
Prompt Fallback Applied

True when the set fell back to prompt-only representation.

boolean
auto_prompt_applied
Auto Prompt Applied

True when the set’s auto prompt addition was appended to the prompt. Informational: the text rides on top of whatever else the set contributed and is not a degradation.

boolean
lora_available_but_incompatible
Lora Available But Incompatible

True when SBMC has a LoRA for this set on another base model but not the one used.

boolean
skipped_not_applicable
Skipped Not Applicable

True when the set isn’t applicable to the chosen model (its modality / applicable base models exclude it) so no LoRA or assets were applied.

boolean
skipped_irrelevant_category
Skipped Irrelevant Category

True when the set’s category means nothing for the chosen model’s modality (a camera move on an image model), so it was dropped entirely, prompt text included. Implies skipped_not_applicable.

boolean
reference_sets_degraded
Reference Sets Degraded

True when at least one attached reference set did not meaningfully contribute. The run still costs Creative Units.

boolean
reference_sets_warning
Reference Sets Warning

Names each degraded reference set and why, or null when none is degraded.

string
nullable
expected_events
Expected Events

Deliveries this run will produce, resolved when it was submitted. Empty when no webhook was supplied. A generation reports its own outcome, and additionally produces a scoring run when this scope has automatic scoring rules — so this is how to tell ‘more is coming’ from ‘that was everything’. Best-effort: a rule turned off mid-run can still remove an event listed here.

Array<string>
default:
Allowed values: inference.completed inference.failed inference.cancelled training.succeeded training.failed scoring_run.completed scoring_run.failed workflow_run.succeeded workflow_run.failed workflow_run.cancelled
Example
{
  "status": "in_progress",
  "reference_set_contributions": [],
  "reference_sets_degraded": false,
  "expected_events": []
}

401

Section titled “401”

Unauthenticated — missing or invalid Bearer token.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

403

Section titled “403”

Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

404

Section titled “404”

Resource not found.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

409

Section titled “409”

The outcome of the request with this Idempotency-Key is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in Retry-After.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

422

Section titled “422”

Invalid input parameters, or an Idempotency-Key reused for a different request.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

429

Section titled “429”

Rate limited — retry after the number of seconds in Retry-After.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

500

Section titled “500”

Internal server error.

Media typeapplication/problem+json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
Example
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}