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_id`required	string (uuid)	—	The user's workspace id.
`inference_tool_key`required	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_id`required	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.