# run_inference_tool

Run a Layer tool, such as \`image.upscale\`, on one of its base models: the one named, else the  
tool's default for the user.

Read the tool's fields with \`get\_inference\_tool\` first. \`input\` holds those fields, and the tool sets  
the values it fixes. An edit takes the file it works on as \`source\_file\_id\`, and a tool that takes a  
mask takes it as \`mask\_file\_id\`; every file is given by ID. The run lands in a session: pass  
\`session\_id\`, \`session\_name\` or \`project\_id\`. The asset it makes reopens in the tool in the Layer app.

Returns immediately with an inference ID, which can be polled with \`get\_forge\_run\` for results.

IMPORTANT: Call tool \`get\_instructions\` first for general platform guidance.

## Parameters

| Parameter                    | Type                       | Default | Description                                                                                                                                                                                                                                                         |
| ---------------------------- | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace\_idrequired        | string (uuid)              | —       | The user's workspace id.                                                                                                                                                                                                                                            |
| inference\_tool\_keyrequired | string                     | —       | The tool's key, such as \`image.upscale\`, from \`list\_inference\_tools\`.                                                                                                                                                                                         |
| base\_model\_id              | string                     | —       | The base model to run the tool on, by ID, slug, name or alias: one of the tool's \`base\_model\_ids\`. Without it, the run takes the tool's \`default\_base\_model\_id\` for the user.                                                                              |
| source\_file\_id             | string (uuid)              | —       | The file an edit works on, from this workspace or public. Required where the tool's schema has \`x-source.required\`; a tool that makes something new takes none.                                                                                                   |
| mask\_file\_id               | string (uuid)              | —       | An image the size of the source, white where the edit may change it and black where the source stays as it is. Only where the tool's schema has \`x-source.takes\_mask\`.                                                                                           |
| batch\_size                  | integer1–16                | 1       | How many outputs the run makes (1-16). More than 1 needs a tool and a model that batch.                                                                                                                                                                             |
| input                        | object                     | —       | The fields of the tool's schema on the model, from \`get\_inference\_tool\`, with files by \`file\_id\`. A field left out takes its default, and the tool sets the values it fixes.                                                                                 |
| reference\_sets              | ForgeReferenceSetInput\[\] | \[\]    | Reference sets to apply, up to 25, from \`list\_reference\_sets\`. Some models need one: an ElevenLabs voice for a voice change or speech, an animation preset for Tripo's animate. A run on such a model without one is refused with \`REFERENCE\_SET\_REQUIRED\`. |
| set\_idrequired              | string (uuid)              | —       | Reference Set ID, from \`list\_reference\_sets\`.                                                                                                                                                                                                                   |
| weight                       | number0–2                  | 1       | Weight for the set's LoRA adapter when one applies. 1.0 = as trained; lower weakens, higher over-applies. Ignored for sets applied as reference images or prompt text.                                                                                              |
| session\_id                  | string (uuid)              | —       | The Session ID to attach the results to.                                                                                                                                                                                                                            |
| session\_name                | string                     | —       | Creates a new session with this name. Pass \`session\_name\` or \`session\_id\`, not both.                                                                                                                                                                          |
| project\_id                  | string (uuid)              | —       | Optional project to file the work in; use list\_projects to find project ids. Without \`session\_id\` or \`session\_name\`, a new unnamed session is created in the project. With \`session\_id\`, that session must already be in this project.                    |