Execute inference
Viewing v2— current version
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>"}'import requests
url = "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/inferences"
payload = { "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>"}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/v2/workspaces/:workspace_id/inferences';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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>"}'};
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/v2/workspaces/:workspace_id/inferences"
payload := strings.NewReader("{\n \"base_model_id\": \"<string>\",\n \"reference_sets\": [],\n \"modality\": \"text\",\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 \"guidance_files\": [],\n \"seed\": -1,\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/v2/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([ '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' => 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, 'guidance_files' => [
], 'seed' => -1, '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 \"base_model_id\": \"<string>\",\n \"reference_sets\": [],\n \"modality\": \"text\",\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 \"guidance_files\": [],\n \"seed\": -1,\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/v2/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/v2/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 \"base_model_id\": \"<string>\",\n \"reference_sets\": [],\n \"modality\": \"text\",\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 \"guidance_files\": [],\n \"seed\": -1,\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_bodyvar client = new RestClient("https://api.app.layer.ai/api/v2/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 \"base_model_id\": \"<string>\",\n \"reference_sets\": [],\n \"modality\": \"text\",\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 \"guidance_files\": [],\n \"seed\": -1,\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);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).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Id of the workspace that owns the resource.
Id of the workspace that owns the resource.
Request Bodyrequired
Section titled “Request Bodyrequired”REST request body for executing an inference. workspace_id comes from path.
object
Reference sets to apply, up to 10.
object
Reference set ID from GET /v2/workspaces/{workspace_id}/reference-sets.
Weight for the set’s LoRA adapter when one applies. Ignored for sets applied as reference images or prompt text.
Number of outputs (1-16).
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.
Reference images/files to guide generation.
Random seed. -1 for random.
Responses
Section titled “Responses”Successful Response
object
Unique identifier for this inference run.
Current status: IN_PROGRESS.
Suggested polling interval in seconds.
Timestamp of when the run was created.
Inference parameters after model-specific normalization.
These reflect the actual values used for generation, including model defaults applied for any parameters not explicitly set.
Base model used for the run, resolved or auto-picked.
Per-set summary of what each reference set contributed.
object
True when a LoRA finetune was applied for this set.
True when an animation (Meshy rigging action) finetune was applied for this set.
True when a voice (ElevenLabs) finetune was applied for this set.
Number of assets successfully mapped to guidance inputs.
True when the set fell back to prompt-only representation.
True when SBMC has a LoRA for this set on another base model but not the one used.
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.
True when at least one attached reference set did not meaningfully contribute. The run still costs Creative Units.
Example
{ "status": "in_progress", "reference_set_contributions": [], "reference_sets_degraded": false}Unauthenticated — missing or invalid Bearer token.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Forbidden — insufficient permissions.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Resource not found.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Invalid input parameters.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Rate limited — too many concurrent requests.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Internal server error.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}