Skip to content

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>",
"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,
"fps": 0,
"video_effects": [],
"use_ta_pose": true,
"pose_mode": "A_POSE",
"include_textures": true,
"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,
"guidance_files": [],
"seed": -1,
"mask": {
"file_id": "<uuid>",
"for_transparency": true,
"for_nontransparency": true,
"edge_radius": 0
},
"session_name": "<string>"
}'

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), and INPUT_FILE_REQUIRED (422 — the sets select an edit-only model with no asset to edit).

workspace_id
required
Workspace Id

Id of the workspace that owns the resource.

string format: uuid

Id of the workspace that owns the resource.

Media typeapplication/json
ExecuteInferenceV2Request

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

object
base_model_id
Any of:
string
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
prompt
Any of:
string
<= 100000 characters
width
Any of:
integer
> 0
height
Any of:
integer
> 0
batch_size
Batch Size

Number of outputs (1-16).

integer
default: 4 >= 1 <= 16
num_inference_steps
Any of:
integer
> 0
guidance_scale
Any of:
number
prompt_strength
Any of:
number
<= 1
quality
Any of:
string
Allowed values: low medium high
sharpness
Any of:
number
duration_seconds
Any of:
number
> 0
generate_audio
Any of:
boolean
keep_audio
Any of:
boolean
fps
Any of:
integer
> 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
Any of:
number
<= 100
use_ta_pose
Any of:
boolean
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
Any of:
boolean
quad_mesh
Any of:
boolean
pbr_materials
Any of:
boolean
low_poly
Any of:
boolean
generate_parts
Any of:
boolean
face_limit
Any of:
integer
> 0
stability
Any of:
number
<= 1
use_speaker_boost
Any of:
boolean
similarity_boost
Any of:
number
<= 1
style_exaggeration
Any of:
number
<= 1
speed
Any of:
number
> 0
upscale_ratio
Any of:
number
creativity
Any of:
number
resemblance
Any of:
number
vectorize
Any of:
boolean
remove_background
Any of:
boolean
reframe
Any of:
boolean
refill
Any of:
boolean
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 init_mesh texture_image element_frontal_image element_reference_image element_video init_audio reference_audio
weight
Any of:
number
<= 1
seed
Seed

Random seed. -1 for random.

integer
default: -1
mask
Any of:
ForgeMaskInput
object
file_id
Any of:
string format: uuid
for_transparency
Any of:
boolean
for_nontransparency
Any of:
boolean
edge_radius
Edge Radius

Mask edge blur radius in pixels.

integer
0
session_name
Any of:
string
<= 255 characters

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
Any of:
number
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
Any of:
string format: uuid
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
Any of:
integer
height
Any of:
integer
batch_size
Any of:
integer
num_inference_steps
Any of:
integer
guidance_scale
Any of:
number
duration_seconds
Any of:
number
fps
Any of:
integer
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
Any of:
string format: uuid
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
prompt_fallback_applied
Prompt Fallback Applied

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

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
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
Any of:
string
Example
{
"status": "in_progress",
"reference_set_contributions": [],
"reference_sets_degraded": false
}

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

Forbidden — insufficient permissions.

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

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

Invalid input parameters.

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

Rate limited — too many concurrent requests.

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

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