Execute inference

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

import requests

url = "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences"

payload = {
    "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,
    "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,
    "seed": -1,
    "guidance_files": [],
    "mask": {
        "file_id": "<uuid>",
        "for_transparency": True,
        "for_nontransparency": True,
        "edge_radius": 0
    },
    "session_name": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const url = 'https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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,"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,"seed":-1,"guidance_files":[],"mask":{"file_id":"<uuid>","for_transparency":true,"for_nontransparency":true,"edge_radius":0},"session_name":"<string>"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences"

  payload := strings.NewReader("{\n  \"model_id\": \"<uuid>\",\n  \"weight\": 1,\n  \"prompt\": \"<string>\",\n  \"width\": 0,\n  \"height\": 0,\n  \"batch_size\": 4,\n  \"num_inference_steps\": 0,\n  \"guidance_scale\": 0,\n  \"prompt_strength\": 0,\n  \"quality\": \"low\",\n  \"sharpness\": 0,\n  \"duration_seconds\": 0,\n  \"generate_audio\": true,\n  \"keep_audio\": true,\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"quad_mesh\": true,\n  \"pbr_materials\": true,\n  \"low_poly\": true,\n  \"generate_parts\": true,\n  \"face_limit\": 0,\n  \"stability\": 0,\n  \"use_speaker_boost\": true,\n  \"similarity_boost\": 0,\n  \"style_exaggeration\": 0,\n  \"speed\": 0,\n  \"upscale_ratio\": 0,\n  \"creativity\": 0,\n  \"resemblance\": 0,\n  \"vectorize\": true,\n  \"remove_background\": true,\n  \"reframe\": true,\n  \"refill\": true,\n  \"seed\": -1,\n  \"guidance_files\": [],\n  \"mask\": {\n    \"file_id\": \"<uuid>\",\n    \"for_transparency\": true,\n    \"for_nontransparency\": true,\n    \"edge_radius\": 0\n  },\n  \"session_name\": \"<string>\"\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => null,
    'keep_audio' => null,
    'fps' => 0,
    'video_effects' => [

    ],
    'use_ta_pose' => null,
    'pose_mode' => 'A_POSE',
    'include_textures' => null,
    'quad_mesh' => null,
    'pbr_materials' => null,
    'low_poly' => null,
    'generate_parts' => null,
    'face_limit' => 0,
    'stability' => 0,
    'use_speaker_boost' => null,
    'similarity_boost' => 0,
    'style_exaggeration' => 0,
    'speed' => 0,
    'upscale_ratio' => 0,
    'creativity' => 0,
    'resemblance' => 0,
    'vectorize' => null,
    'remove_background' => null,
    'reframe' => null,
    'refill' => null,
    'seed' => -1,
    'guidance_files' => [

    ],
    'mask' => [
        'file_id' => '<uuid>',
        'for_transparency' => null,
        'for_nontransparency' => null,
        'edge_radius' => 0
    ],
    'session_name' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"model_id\": \"<uuid>\",\n  \"weight\": 1,\n  \"prompt\": \"<string>\",\n  \"width\": 0,\n  \"height\": 0,\n  \"batch_size\": 4,\n  \"num_inference_steps\": 0,\n  \"guidance_scale\": 0,\n  \"prompt_strength\": 0,\n  \"quality\": \"low\",\n  \"sharpness\": 0,\n  \"duration_seconds\": 0,\n  \"generate_audio\": true,\n  \"keep_audio\": true,\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"quad_mesh\": true,\n  \"pbr_materials\": true,\n  \"low_poly\": true,\n  \"generate_parts\": true,\n  \"face_limit\": 0,\n  \"stability\": 0,\n  \"use_speaker_boost\": true,\n  \"similarity_boost\": 0,\n  \"style_exaggeration\": 0,\n  \"speed\": 0,\n  \"upscale_ratio\": 0,\n  \"creativity\": 0,\n  \"resemblance\": 0,\n  \"vectorize\": true,\n  \"remove_background\": true,\n  \"reframe\": true,\n  \"refill\": true,\n  \"seed\": -1,\n  \"guidance_files\": [],\n  \"mask\": {\n    \"file_id\": \"<uuid>\",\n    \"for_transparency\": true,\n    \"for_nontransparency\": true,\n    \"edge_radius\": 0\n  },\n  \"session_name\": \"<string>\"\n}");
Request request = new Request.Builder()
  .url("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

require 'uri'
require 'net/http'

url = URI("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model_id\": \"<uuid>\",\n  \"weight\": 1,\n  \"prompt\": \"<string>\",\n  \"width\": 0,\n  \"height\": 0,\n  \"batch_size\": 4,\n  \"num_inference_steps\": 0,\n  \"guidance_scale\": 0,\n  \"prompt_strength\": 0,\n  \"quality\": \"low\",\n  \"sharpness\": 0,\n  \"duration_seconds\": 0,\n  \"generate_audio\": true,\n  \"keep_audio\": true,\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"quad_mesh\": true,\n  \"pbr_materials\": true,\n  \"low_poly\": true,\n  \"generate_parts\": true,\n  \"face_limit\": 0,\n  \"stability\": 0,\n  \"use_speaker_boost\": true,\n  \"similarity_boost\": 0,\n  \"style_exaggeration\": 0,\n  \"speed\": 0,\n  \"upscale_ratio\": 0,\n  \"creativity\": 0,\n  \"resemblance\": 0,\n  \"vectorize\": true,\n  \"remove_background\": true,\n  \"reframe\": true,\n  \"refill\": true,\n  \"seed\": -1,\n  \"guidance_files\": [],\n  \"mask\": {\n    \"file_id\": \"<uuid>\",\n    \"for_transparency\": true,\n    \"for_nontransparency\": true,\n    \"edge_radius\": 0\n  },\n  \"session_name\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

var client = new RestClient("https://api.app.layer.ai/api/v1/workspaces/:workspace_id/inferences");
var request = new RestRequest("", Method.Post);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model_id\": \"<uuid>\",\n  \"weight\": 1,\n  \"prompt\": \"<string>\",\n  \"width\": 0,\n  \"height\": 0,\n  \"batch_size\": 4,\n  \"num_inference_steps\": 0,\n  \"guidance_scale\": 0,\n  \"prompt_strength\": 0,\n  \"quality\": \"low\",\n  \"sharpness\": 0,\n  \"duration_seconds\": 0,\n  \"generate_audio\": true,\n  \"keep_audio\": true,\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"quad_mesh\": true,\n  \"pbr_materials\": true,\n  \"low_poly\": true,\n  \"generate_parts\": true,\n  \"face_limit\": 0,\n  \"stability\": 0,\n  \"use_speaker_boost\": true,\n  \"similarity_boost\": 0,\n  \"style_exaggeration\": 0,\n  \"speed\": 0,\n  \"upscale_ratio\": 0,\n  \"creativity\": 0,\n  \"resemblance\": 0,\n  \"vectorize\": true,\n  \"remove_background\": true,\n  \"reframe\": true,\n  \"refill\": true,\n  \"seed\": -1,\n  \"guidance_files\": [],\n  \"mask\": {\n    \"file_id\": \"<uuid>\",\n    \"for_transparency\": true,\n    \"for_nontransparency\": true,\n    \"edge_radius\": 0\n  },\n  \"session_name\": \"<string>\"\n}", ParameterType.RequestBody);
var response = client.Execute(request);

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

bearerAuth

Parameters

Path Parameters

workspace_id

required

Workspace Id

string format: uuid

Request Body^required

application/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

Any of:

string
null

string

<= 100000 characters

width

Any of:

integer
null

integer

> 0

height

Any of:

integer
null

integer

> 0

batch_size

Batch Size

Number of outputs (1-16).

integer

default: 4 >= 1 <= 16

num_inference_steps

Any of:

integer
null

integer

> 0

guidance_scale

Any of:

number
null

number

prompt_strength

Any of:

number
null

number

<= 1

quality

Any of:

string
null

string

Allowed values: low medium high

sharpness

Any of:

number
null

number

duration_seconds

Any of:

number
null

number

> 0

generate_audio

Any of:

boolean
null

boolean

keep_audio

Any of:

boolean
null

boolean

fps

Any of:

integer
null

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
null

number

<= 100

use_ta_pose

Any of:

boolean
null

boolean

pose_mode

Any of:

PoseMode
null

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
null

boolean

quad_mesh

Any of:

boolean
null

boolean

pbr_materials

Any of:

boolean
null

boolean

low_poly

Any of:

boolean
null

boolean

generate_parts

Any of:

boolean
null

boolean

face_limit

Any of:

integer
null

integer

> 0

stability

Any of:

number
null

number

<= 1

use_speaker_boost

Any of:

boolean
null

boolean

similarity_boost

Any of:

number
null

number

<= 1

style_exaggeration

Any of:

number
null

number

<= 1

speed

Any of:

number
null

number

> 0

upscale_ratio

Any of:

number
null

number

creativity

Any of:

number
null

number

resemblance

Any of:

number
null

number

vectorize

Any of:

boolean
null

boolean

remove_background

Any of:

boolean
null

boolean

reframe

Any of:

boolean
null

boolean

refill

Any of:

boolean
null

boolean

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 reference_image editing_reference scribble color_sketch pose depth canny softedge_hed segmentation lineart prompt face first_frame last_frame init_video reference_video init_mesh texture_image element_frontal_image element_reference_image element_video init_audio audio

weight

Any of:

number
null

number

<= 1

mask

Any of:

ForgeMaskInput
null

ForgeMaskInput

object

file_id

Any of:

string
null

string format: uuid

for_transparency

Any of:

boolean
null

boolean

for_nontransparency

Any of:

boolean
null

boolean

edge_radius

Edge Radius

Mask edge blur radius in pixels.

integer

session_name

Any of:

string
null

string

<= 255 characters

Responses

202

Successful Response

application/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

Any of:

number
null

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
null

string format: uuid

normalized_parameters

Any of:

NormalizedInferenceParameters
null

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

Any of:

integer
null

integer

height

Any of:

integer
null

integer

batch_size

Any of:

integer
null

integer

num_inference_steps

Any of:

integer
null

integer

guidance_scale

Any of:

number
null

number

duration_seconds

Any of:

number
null

number

fps

Any of:

integer
null

integer

Example

{
  "status": "in_progress"
}

401

Unauthenticated — missing or invalid Bearer token.

application/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

Forbidden — insufficient permissions.

application/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

Resource not found.

application/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

Invalid input parameters.

application/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

Rate limited — too many concurrent requests.

application/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

Internal server error.

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

Execute inference

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

202

Example

401

Example

403

Example

404

Example

422

Example

429

Example

500

Example

Request Body^required