Skip to content
Layer Docs

Execute inference

Viewing v1— superseded by v2

POST
/v1/workspaces/{workspace_id}/inferences
curl --request POST \
  --url https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model_id": "<uuid>",
  "weight": 1,
  "prompt": "<string>",
  "width": 0,
  "height": 0,
  "batch_size": 4,
  "num_inference_steps": 0,
  "guidance_scale": 0,
  "prompt_strength": 0,
  "quality": "low",
  "sharpness": 0,
  "duration_seconds": 0,
  "generate_audio": true,
  "keep_audio": 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,
  "stability": 0,
  "use_speaker_boost": true,
  "similarity_boost": 0,
  "style_exaggeration": 0,
  "speed": 0,
  "upscale_ratio": 0,
  "creativity": 0,
  "resemblance": 0,
  "vectorize": true,
  "remove_background": true,
  "reframe": true,
  "refill": true,
  "seed": -1,
  "guidance_files": [],
  "mask": {
    "file_id": "<uuid>",
    "for_transparency": true,
    "for_nontransparency": true,
    "edge_radius": 0
  },
  "session_name": "<string>"
}'

v1 is superseded. v1 was superseded by v2 on 2026-08-26. A sunset date has not been announced yet; v1 will be deprecated as a whole before removal. Migrate with the v2 migration guide.

Start an AI inference (image, video, 3D, or audio). Returns immediately with an ID. Poll with GET /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.

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
ExecuteInferenceRequest

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

object
model_id
required
Model Id

Model/style ID to use for generation.

string format: uuid
weight
Weight

Style/LoRA strength applied to the model. 1.0 = as trained; lower weakens, higher over-applies the style. Only affects LoRA/adapter-backed styles; ignored for models without a trainable adapter.

number
default: 1 <= 2
prompt
Prompt

Text prompt.

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
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
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
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
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
vectorize
Vectorize

Vectorize the output image.

boolean
nullable
remove_background
Remove Background

Remove background from output.

boolean
nullable
reframe
Reframe

Reframe/extend the image.

boolean
nullable
refill
Refill

Outpaint/refill transparent areas.

boolean
nullable
seed
Seed

Random seed. -1 for random.

integer
default: -1
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
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

Session name.

string
nullable <= 255 characters

Responses

Section titled “Responses”

202

Section titled “202”

Successful Response

Media typeapplication/json
ExecuteForgeOutput
object
inference_id
required
Inference Id

Unique identifier for this forge 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:
NormalizedInferenceParameters

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
Example
{
  "status": "in_progress"
}

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."
}