# Execute inference

POST

/v1/workspaces/{workspace\_id}/inferences

```bash
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 '{
  "subtitle_preset": "<string>",
  "subtitle_color": "<string>",
  "subtitle_secondary_color": "<string>",
  "subtitle_alignment": "top",
  "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>"
  ],
  "segment_target": "CHARACTER",
  "segment_parts": 0,
  "segment_level": "LOW",
  "segment_strength": 0,
  "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>"
}'
```

```python
import requests


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


payload = {
    "subtitle_preset": "<string>",
    "subtitle_color": "<string>",
    "subtitle_secondary_color": "<string>",
    "subtitle_alignment": "top",
    "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": None,
                "duration_seconds": None,
                "positive_styles": None,
                "negative_styles": None,
                "lines": None
            }
        ],
        "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>"],
    "segment_target": "CHARACTER",
    "segment_parts": 0,
    "segment_level": "LOW",
    "segment_strength": 0,
    "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())
```

```js
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: '{"subtitle_preset":"<string>","subtitle_color":"<string>","subtitle_secondary_color":"<string>","subtitle_alignment":"top","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>"],"segment_target":"CHARACTER","segment_parts":0,"segment_level":"LOW","segment_strength":0,"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);
}
```

```go
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  \"subtitle_preset\": \"<string>\",\n  \"subtitle_color\": \"<string>\",\n  \"subtitle_secondary_color\": \"<string>\",\n  \"subtitle_alignment\": \"top\",\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  \"instrumental\": true,\n  \"loop\": true,\n  \"output_format\": \"mp3\",\n  \"lyrics\": \"<string>\",\n  \"composition_plan\": {\n    \"positive_styles\": [],\n    \"negative_styles\": [],\n    \"sections\": [\n      {\n        \"name\": null,\n        \"duration_seconds\": null,\n        \"positive_styles\": null,\n        \"negative_styles\": null,\n        \"lines\": null\n      }\n    ],\n    \"respect_section_durations\": true\n  },\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"detailed_geometry\": true,\n  \"remesh_geometry\": true,\n  \"texture_resolution\": \"RES_2K\",\n  \"remove_lighting\": true,\n  \"mesh_density\": \"ULTRA\",\n  \"preserve_uvs\": true,\n  \"segment_by\": \"AUTO\",\n  \"segment_part_names\": [\n    \"<string>\"\n  ],\n  \"segment_target\": \"CHARACTER\",\n  \"segment_parts\": 0,\n  \"segment_level\": \"LOW\",\n  \"segment_strength\": 0,\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
<?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([
    'subtitle_preset' => '<string>',
    'subtitle_color' => '<string>',
    'subtitle_secondary_color' => '<string>',
    'subtitle_alignment' => 'top',
    '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,
    'instrumental' => null,
    'loop' => null,
    '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' => null
    ],
    'fps' => 0,
    'video_effects' => [


    ],
    'use_ta_pose' => null,
    'pose_mode' => 'A_POSE',
    'include_textures' => null,
    'detailed_geometry' => null,
    'remesh_geometry' => null,
    'texture_resolution' => 'RES_2K',
    'remove_lighting' => null,
    'mesh_density' => 'ULTRA',
    'preserve_uvs' => null,
    'segment_by' => 'AUTO',
    'segment_part_names' => [
        '<string>'
    ],
    'segment_target' => 'CHARACTER',
    'segment_parts' => 0,
    'segment_level' => 'LOW',
    'segment_strength' => 0,
    '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;
}
```

```java
OkHttpClient client = new OkHttpClient();


MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"subtitle_preset\": \"<string>\",\n  \"subtitle_color\": \"<string>\",\n  \"subtitle_secondary_color\": \"<string>\",\n  \"subtitle_alignment\": \"top\",\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  \"instrumental\": true,\n  \"loop\": true,\n  \"output_format\": \"mp3\",\n  \"lyrics\": \"<string>\",\n  \"composition_plan\": {\n    \"positive_styles\": [],\n    \"negative_styles\": [],\n    \"sections\": [\n      {\n        \"name\": null,\n        \"duration_seconds\": null,\n        \"positive_styles\": null,\n        \"negative_styles\": null,\n        \"lines\": null\n      }\n    ],\n    \"respect_section_durations\": true\n  },\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"detailed_geometry\": true,\n  \"remesh_geometry\": true,\n  \"texture_resolution\": \"RES_2K\",\n  \"remove_lighting\": true,\n  \"mesh_density\": \"ULTRA\",\n  \"preserve_uvs\": true,\n  \"segment_by\": \"AUTO\",\n  \"segment_part_names\": [\n    \"<string>\"\n  ],\n  \"segment_target\": \"CHARACTER\",\n  \"segment_parts\": 0,\n  \"segment_level\": \"LOW\",\n  \"segment_strength\": 0,\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();
```

```ruby
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  \"subtitle_preset\": \"<string>\",\n  \"subtitle_color\": \"<string>\",\n  \"subtitle_secondary_color\": \"<string>\",\n  \"subtitle_alignment\": \"top\",\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  \"instrumental\": true,\n  \"loop\": true,\n  \"output_format\": \"mp3\",\n  \"lyrics\": \"<string>\",\n  \"composition_plan\": {\n    \"positive_styles\": [],\n    \"negative_styles\": [],\n    \"sections\": [\n      {\n        \"name\": null,\n        \"duration_seconds\": null,\n        \"positive_styles\": null,\n        \"negative_styles\": null,\n        \"lines\": null\n      }\n    ],\n    \"respect_section_durations\": true\n  },\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"detailed_geometry\": true,\n  \"remesh_geometry\": true,\n  \"texture_resolution\": \"RES_2K\",\n  \"remove_lighting\": true,\n  \"mesh_density\": \"ULTRA\",\n  \"preserve_uvs\": true,\n  \"segment_by\": \"AUTO\",\n  \"segment_part_names\": [\n    \"<string>\"\n  ],\n  \"segment_target\": \"CHARACTER\",\n  \"segment_parts\": 0,\n  \"segment_level\": \"LOW\",\n  \"segment_strength\": 0,\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
```

```csharp
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  \"subtitle_preset\": \"<string>\",\n  \"subtitle_color\": \"<string>\",\n  \"subtitle_secondary_color\": \"<string>\",\n  \"subtitle_alignment\": \"top\",\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  \"instrumental\": true,\n  \"loop\": true,\n  \"output_format\": \"mp3\",\n  \"lyrics\": \"<string>\",\n  \"composition_plan\": {\n    \"positive_styles\": [],\n    \"negative_styles\": [],\n    \"sections\": [\n      {\n        \"name\": null,\n        \"duration_seconds\": null,\n        \"positive_styles\": null,\n        \"negative_styles\": null,\n        \"lines\": null\n      }\n    ],\n    \"respect_section_durations\": true\n  },\n  \"fps\": 0,\n  \"video_effects\": [],\n  \"use_ta_pose\": true,\n  \"pose_mode\": \"A_POSE\",\n  \"include_textures\": true,\n  \"detailed_geometry\": true,\n  \"remesh_geometry\": true,\n  \"texture_resolution\": \"RES_2K\",\n  \"remove_lighting\": true,\n  \"mesh_density\": \"ULTRA\",\n  \"preserve_uvs\": true,\n  \"segment_by\": \"AUTO\",\n  \"segment_part_names\": [\n    \"<string>\"\n  ],\n  \"segment_target\": \"CHARACTER\",\n  \"segment_parts\": 0,\n  \"segment_level\": \"LOW\",\n  \"segment_strength\": 0,\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);
```

* Layer API

> **v1 is superseded.** v1 was superseded by [v2](/docs/v2/rest-api/operations/executeinferencev2) 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](/docs/migration).

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](/docs/v1/rest-api#bearerauth)**
* **[oauth2](/docs/v1/rest-api#oauth2)**
* **[serviceAccount](/docs/v1/rest-api#serviceaccount)**  
generation:write

## Parameters

### 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

**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

_ExecuteInferenceRequest_

REST request body for executing an inference. workspace\_id comes from path.

object

**subtitle\_preset**

_Subtitle Preset_

Caption style, spelled exactly as one of the model’s `subtitle_presets`: any other name is quoted at the default style and refused at launch. Its `subtitle_dynamic_presets` animate word by word and bill at a higher rate, so pass the same preset to the estimate. Omit for the model’s default style.

string

nullable

**subtitle\_color**

_Subtitle Color_

Caption text colour as hex (`#FFFFFF`), for models whose capabilities report `subtitle_primary_color`.

string

nullable /^#(\[0-9A-Fa-f\]{3}){1,2}$/

**subtitle\_secondary\_color**

_Subtitle Secondary Color_

Colour of the words the model emphasises, as hex, for models whose capabilities report `subtitle_secondary_color`.

string

nullable /^#(\[0-9A-Fa-f\]{3}){1,2}$/

**subtitle\_alignment**

_Subtitle Alignment_

Where the captions sit vertically, for models whose capabilities report `subtitle_alignment`.

string

nullable

Allowed values: top center bottom

**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**

_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

**null**

null

**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**

_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

**null**

null

**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**

_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

**null**

null

**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**

_TextureResolution_

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

Offered where the model’s `texture_resolutions` capability lists it (Meshy’s and Tripo’s own APIs).

string

Allowed values: RES\_2K RES\_4K RES\_8K

**null**

null

**remove\_lighting**

_Remove Lighting_

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

boolean

nullable

**mesh\_density**

Any of:

**MeshDensity**

_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

**null**

null

**preserve\_uvs**

_Preserve Uvs_

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

boolean

nullable

**segment\_by**

Any of:

**SegmentBy**

_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

**null**

null

**segment\_part\_names**

_Segment Part Names_

Parts to split along when segment\_by is PARTS, at most 10.

Array<string>

nullable <= 10 items

**segment\_target**

Any of:

**SegmentTarget**

_SegmentTarget_

What a mesh-segmentation model treats the input as, selecting its split strategy. `CHARACTER` splits a humanoid mesh with a body-part template; `GENERAL` splits any mesh by granularity level (e.g. Hi3D Parts).

string

Allowed values: CHARACTER GENERAL

**null**

null

**segment\_parts**

_Segment Parts_

How many parts a CHARACTER split makes. Support varies by model.

integer

nullable \>= 1

**segment\_level**

Any of:

**SegmentLevel**

_SegmentLevel_

Split granularity for a general-target segmentation (more parts as it rises). Only meaningful when the target is `GENERAL`.

string

Allowed values: LOW MEDIUM HIGH

**null**

null

**segment\_strength**

_Segment Strength_

How aggressively a mesh split cuts: higher makes more parts. Support varies by model.

integer

nullable \>= 1

**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**

_MultiViewSlot_

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

string

Allowed values: FRONT LEFT BACK RIGHT

**null**

null

**annotations**

Any of:

**ImageAnnotations**

_ImageAnnotations_

The marks drawn on one image, in the order they are numbered.

object

**items**

_Items_

Array<object>

default: <= 32 items

_ImageAnnotation_

One mark. Its number, on the image and in the legend, is its position in the list plus one.

object

**id**

required

_Id_

string

\>= 1 characters <= 64 characters

**kind**

required

_ImageAnnotationKind_

string

Allowed values: BOX ELLIPSE ARROW FREEHAND PIN

**intent**

_ImageAnnotationIntent_

string

default: EDIT

Allowed values: EDIT REMOVE MOVE

**points**

required

_Points_

Array<object>

_ImageAnnotationPoint_

A point on the image, from (0, 0) at the top left to (1, 1) at the bottom right.

The image is the one the slot sends, before the model fits it: the file as stored (or, for a video or a 3D model, the frame taken from it, `video_to_image` / `mesh_to_image`) after its flip, scale, rotation and crop. Marks are the last edit on it.

object

**x**

required

_X_

number

<= 1

**y**

required

_Y_

number

<= 1

**note**

_Note_

string

nullable <= 500 characters

**color**

_Color_

string

nullable

**source\_id**

_Source Id_

string

nullable

**color**

_Color_

string

nullable

**null**

null

**mask**

Any of:

**ForgeMaskInput**

_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

**null**

null

**session\_name**

_Session Name_

Session name.

string

nullable <= 255 characters

## Responses

### 202

Successful Response

_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**

_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

**null**

null

##### Example

```json
{
  "status": "in_progress"
}
```

### 401

Unauthenticated — missing or invalid Bearer token.

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 403

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

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 404

Resource not found.

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 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`.

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 422

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

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 429

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

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```

### 500

Internal server error.

object

**type**

required

string

**title**

required

string

**status**

required

integer

**detail**

required

string

**error\_code**

required

Machine-readable error code: the last path segment of `type`.

string

##### Example

```json
{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description.",
  "error_code": "ERROR_CODE"
}
```