execute_forge

Execute a forge run to generate images, videos, 3D models, or audio.

Pass a `base_model_id`, at least one entry in `reference_sets`, or both. With reference sets
and no base model, a compatible model is picked automatically from the sets.

Returns immediately with an inference ID, which can be polled with `get_forge_run` for results.

Call `get_forge_instructions` first for full forge lifecycle guidance.

Parameters

Parameter	Type	Default	Description
base_model_id	string	—	Base model to run, given as an id (e.g. flux-dev), display name, or community alias (e.g. 'Nano Banana 2'). Not required when passing reference sets — a compatible model is then auto-picked from them. Required otherwise. Find ids with `list_base_models`.
reference_sets	ForgeReferenceSetInput[]	[]	Reference Sets to translate into guidance inputs and prompt text for the target model. Required when no base_model_id is given — the model is then auto-picked from the sets. Find ids with `list_reference_sets`.
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.
modality	enum	—	Output modality: image, video, three_d, or audio. Used to disambiguate reference-set translation; inferred from the reference sets when omitted. Not required with a base_model_id. One of: text, image, audio, video, three_d, playable
prompt	string	—	Text prompt describing what to generate.
width	integer>0	—	Output width in pixels. Pass both width and height whenever the output must have a specific aspect ratio: with either one absent and an init image, editing reference, or first frame attached, the output geometry is taken from that file rather than from a model default.
height	integer>0	—	Output height in pixels. Pass both width and height whenever the output must have a specific aspect ratio: with either one absent and an init image, editing reference, or first frame attached, the output geometry is taken from that file rather than from a model default.
batch_size	integer1–16	4	Number of outputs to generate (1-16).
seed	integer	-1	Random seed. -1 for random.
guidance_files	ForgeGuidanceFileInput[]	[]	Reference images/files to guide generation.
file_idrequired	string (uuid)	—	File ID of an uploaded file.
typerequired	string	—	Guidance type: init_image, reference_image, pose, depth, canny, softedge_hed, segmentation, lineart, face, first_frame, last_frame, init_video, reference_video, reference_audio, init_audio, init_mesh, texture_image, scribble, color_sketch. See model capabilities for supported types per model.
weight	number0–1	—	Influence weight (0-1). Defaults to 0.5 for init_image, 1 for others.
mask	ForgeMaskInput	—	Mask for inpainting/outpainting. Provide file_id or transparency flags.
file_id	string (uuid)	—	Mask image file ID.
for_transparency	boolean	—	Use transparent areas as mask.
for_nontransparency	boolean	—	Use non-transparent areas as mask.
edge_radius	integer≥0	0	Mask edge blur radius in pixels.
camera	ForgeCameraInput	—	Camera view change relative to the input image: orbit to a side/back/top view, or zoom. Requires the source image attached as an init_image or reference_image guidance file supported by the model, and only models whose capabilities report camera_transform accept it (check get_model / get_base_model). Supply view direction here; dispatch encodes it in the model's required format.
yaw_degrees	number-360–360	—	Orbit horizontally around the subject, in degrees: 90 = right side view, 180 = back view, 270 (or -90) = left side view.
pitch_degrees	number-30–90	—	Camera elevation in degrees: positive looks down (90 = top-down), negative looks up (-30 is the lowest supported angle).
roll_degrees	number	—	Bank around the viewing axis in degrees, clockwise positive. Natively camera-capable models ignore roll.
distance_delta	number	—	Dolly out (positive) / in (negative), in scene units; ~5 spans wide shot to close-up.
fov_delta_degrees	number	—	Field-of-view change in degrees: positive widens (zoom out), negative narrows. Alternative to distance_delta.
num_inference_steps	integer	—	Number of diffusion steps.
guidance_scale	number	—	Guidance scale (CFG).
prompt_strength	number0–1	—	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.
quality	enum	—	Quality level. One of: low, medium, high
sharpness	number	—	Output sharpness.
duration_seconds	number	—	Output length in seconds — video clip length, or audio clip length for models whose duration_seconds_min / duration_seconds_max say they take one.
generate_audio	boolean	—	Generate audio with video.
keep_audio	boolean	—	Keep audio from input video.
fps	integer	—	FPS for LTX video generation (e.g. 25 or 50).
video_effects	ForgeVideoEffectInput[]	[]	Video effects to apply.
typerequired	string	—	Video effect type (UPPERCASE). Common types: GENERAL, ORBIT_360, DOLLY_IN, DOLLY_OUT, ZOOM_IN, ZOOM_OUT, CRANE_UP, CRANE_DOWN, TILT_UP, TILT_DOWN, STATIC, FPV_DRONE, HYPERLAPSE, HANDHELD. See model capabilities for supported effects per model.
weight	number0–100	—	Effect strength (0-100).
frame_extraction_location	enum	—	Which frame to extract from an input video: first, middle, or last. Used by ffmpeg-extract-frame and similar models. One of: first, last, middle, timestamp
use_ta_pose	boolean	—	Deprecated: use pose_mode. Legacy rig-ready-pose toggle for 3D.
pose_mode	enum	—	Rest pose for a character mesh: A_POSE or T_POSE. Support varies by model. One of: A_POSE, T_POSE
include_textures	boolean	—	Include textures in 3D output.
quad_mesh	boolean	—	Generate quad mesh.
pbr_materials	boolean	—	Generate PBR materials.
low_poly	boolean	—	Generate low-poly mesh.
generate_parts	boolean	—	Generate separate parts.
detailed_geometry	boolean	—	Generate denser, more detailed geometry. Costs extra and only some 3D models support it.
export_uv	boolean	—	Set false to omit UV coordinates from the 3D output.
compress_geometry	boolean	—	Return a geometry-compressed mesh. Only some 3D models support it.
face_limit	integer	—	Face/polygon limit for 3D mesh.
stability	number0–1	—	Voice stability (0-1).
similarity_boost	number0–1	—	Voice similarity boost (0-1).
style_exaggeration	number0–1	—	Style exaggeration (0-1).
speed	number	—	Speech speed multiplier (ElevenLabs: 0.7-1.2).
text_normalization	enum	—	How TTS reads out numbers/dates: AUTO, ON, or OFF. One of: AUTO, ON, OFF
temperature	number	—	TTS sampling temperature (Qwen 0-1, Gemini 0-2).
style_instructions	string	—	Free-text delivery guidance for TTS, distinct from the spoken text (e.g. "excited sports commentator"). Qwen and Gemini TTS models only.
upscale_ratio	number	—	Upscale factor (e.g. 2.0, 4.0).
creativity	number	—	Creative variation strength for upscaling.
resemblance	number	—	Resemblance to original for upscaling.
vectorize	boolean	—	Vectorize the output image.
vectorization_mode	enum	—	SVG path mode: 'spline' (curved) or 'polygon' (straight lines). One of: spline, polygon
vectorization_color_mode	enum	—	SVG color output: 'color' or 'binary' (black and white). One of: color, binary
vectorization_filter_speckle	integer0–128	—	Filter out small speckles and noise when vectorizing (0-128).
vectorization_color_precision	integer1–8	—	Color quantization level when vectorizing (1-8).
remove_background	boolean	—	Remove the background. Effective as the standalone operation on a background-removal model; a generation model does not chain removal onto its outputs on this surface.
reframe	boolean	—	Reframe/extend the image.
refill	boolean	—	Outpaint/refill transparent areas.
workspace_idrequired	string (uuid)	—	The user's workspace id.
session_id	string (uuid)	—	The Session ID to attach the results to.
session_name	string	—	Creates a new session with this name. One of `session_name` or `session_id` must specified, but not both.