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, world
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, draft_video, draft_world, draft_mesh. 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.
video_frame	enum	—	For a video file in an image slot (first_frame, last_frame, reference_image, init_image): the frame of it to use. Defaults to its first frame, or its last for last_frame. One of: first, middle, last
video_frame_seconds	number≥0	—	For a video file in an image slot: the frame at this many seconds into it. Overrides video_frame.
view	enum	—	For a model whose capabilities list init_image_views: the view this init_image shows. Tag every source with its view; a view with no image stays empty. A front view is required whenever more than one view is given. One of: FRONT, LEFT, BACK, RIGHT
mask	ForgeMaskInput	—	Mask for inpainting/outpainting. Provide file_id or transparency flags.
file_id	string (uuid)	—	Mask image file ID.
for_transparency	boolean	—	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.
for_nontransparency	boolean	—	Use non-transparent areas as mask.
edge_radius	integer≥0	0	Mask edge blur radius in pixels.
tile_grid	TileGrid	—	Draw a game tile onto a fixed grid, so every tile of a set shares one projection and footprint and snaps together in an engine. Only models whose capabilities report tile_grid accept it. The run draws over a blockout of the grid, so pass no init_image (a reference_image carries the set's look, or the same building for another facing); the output comes back cut out and fitted onto the grid. shape SQUARE (the default) draws an isometric diamond tile, HEXAGON a hex tile with orientation POINTY_TOP (the default) or FLAT_TOP. elevation 30 is 2:1 dimetric for a square (at most 60); a hexagon takes 60 unless set, 90 looking straight down. footprint_width x footprint_depth in cells (a hexagon covers one); height in cell sides (0 for a flat ground tile, about 1 to 2 for a building); facing 0, 90, 180 or 270 turns the camera around a square tile (a hexagon faces 0); tile_width is the delivered width of one cell's outline in px.
shape	enum	SQUARE	One of: SQUARE, HEXAGON
orientation	enum	—	Unset takes the shape's first: DIAMOND for a square, POINTY_TOP for a hexagon. One of: DIAMOND, ALIGNED, POINTY_TOP, FLAT_TOP
elevation	number20–90	—	Unset takes 30 (2:1 dimetric) for a square, 60 for a hexagon.
facing	enum	0	One of: 0, 90, 180, 270
footprint_width	integer1–8	1
footprint_depth	integer1–8	1
height	number0–6	0
tile_width	integer16–1024	128
light_from	enum	left	One of: left, right
output_fit	OutputFit	—	Fit each image output onto a delivery canvas after the run: trim its transparent margin, or place it on a FIXED width x height canvas aligned on an anchor. For a game tile set, a FIXED canvas with anchor BASE stands every tile's base on the same point, so a set shares one sprite size. Omit to deliver the output as generated.
trim	boolean	false
canvas	enum	CONTENT	One of: CONTENT, FIXED
width	integer1–4096	—
height	integer1–4096	—
scale	enum	PLACE	One of: PLACE, SHRINK_AND_PAD, FIT_AND_PAD, FIT_AND_CROP, STRETCH
anchor	enum	CENTER	One of: TOP_LEFT, TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTER, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER, BOTTOM_RIGHT, BASE
padding	integer0–512	0
nine_slice	boolean	—	Deliver each image output as a 9-slice UI element (a button, frame, panel or tab that stretches): after the run, Layer finds the plain band through its middle on each axis, cleans the edges and centre so nothing smears when stretched, and records the insets on the file, ready for a UI kit export. Prompt for ornament in the corners only and a plain middle, on a solid background colour (asked for a transparent one, models paint a checkerboard into the pixels); an image with a centred emblem comes back without insets. Omit for anything that is not stretched.
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. Models offer different rungs of the shared ladder (see a model's `quality_levels`); a rung the model does not offer is clamped to the nearest one it does, never refused. Higher rungs can cost more. One of: minimal, low, medium, high, xhigh, max
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.
draft	boolean	—	Render a quick, low-cost draft instead of the full-quality output, on models whose capabilities report `draft`. Complete a draft you want to keep with the model in its run output's `draft.completion_base_model_id`, passing the draft's file_id as a guidance file of its `draft.completion_guidance_type`.
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.
remesh_geometry	boolean	—	Set false to skip the provider's remesh phase and keep its raw high-density geometry. 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).
lyrics	string	—	Words to be sung, for models whose capabilities report `lyrics`. A separate input from the prompt, which describes the music itself. Structure tags such as [verse] and [chorus] go on their own lines. Leave unset for an instrumental track.
instrumental	boolean	—	Set true to guarantee a track with no vocals. Prose in the prompt does not: these models take a dedicated flag. Use it for background music and for anything that loops.
loop	boolean	—	Set true for audio that repeats with no audible seam, for models whose capabilities report `loop`. The provider composes the clip to loop; asking for it in the prompt does not.
output_format	enum	—	Container for the delivered file, one of the values the model's capabilities list under `output_formats`. Layer never re-encodes a clip, so a model listing none delivers whatever it delivers, and asking one for a container it does not list fails the run rather than returning a different format. One of: mp3, wav, aac, flac
audio_segments	AudioSegment[]	—	Scores a video stretch by stretch, for models whose capabilities report `audio_segments`. The stretches must tile the part of the video being scored with no gaps and no overlaps, so each one's end is the next one's start.
start_secondsrequired	number≥0	—
end_secondsrequired	number≥0	—
promptrequired	string1–∞ chars	—
composition_plan	CompositionPlan	—	The track as an ordered list of sections, for models whose capabilities report `composition_plan`. The plan's own `positive_styles`/`negative_styles` hold for the whole track (genre, era, production character, palette); each section carries only what changes, and a section's `negative_styles` are the only way to keep it empty of something the rest of the track has. A plan SUPERSEDES `prompt`, `duration_seconds` and `instrumental`, which are dropped rather than sent with it, say so in the reply when the user also gave a prompt. Sections run 3-120s each, at most 30 of them, 3s-10min in total.
positive_styles	string[]	[]
negative_styles	string[]	[]
sectionsrequired	MusicSection[]	—
namerequired	string1–100 chars	—
duration_secondsrequired	number3–120	—
positive_styles	string[]	[]
negative_styles	string[]	[]
lines	string[]	[]
respect_section_durations	boolean	true
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_layering	enum	—	SVG shape layering (color mode only): 'stacked' (shapes overlap) or 'cutout' (no overlap). One of: stacked, cutout
vectorization_filter_speckle	integer0–20	—	Drop specks smaller than this many pixels when vectorizing (0-20, default 4).
vectorization_color_precision	integer1–10	—	Color quantization level when vectorizing; lower merges more colors (1-10, default 6).
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.
tileability	boolean	—	Set true for an image that tiles seamlessly, repeating edge to edge with no visible seam. Works with any image generation or editing model: one whose capabilities report `native_tileability` generates the wrap itself (and then takes no LoRA style), any other has its edges joined after it is generated, as `tile_texture` decides. Upscales, layered and vector outputs are not joined. Asking for a seamless texture in the prompt does not make the edges meet.
tile_texture	enum	—	With `tileability` on a model without `native_tileability`, how the edges are joined. ORGANIC (grass, sand, moss, water, rubble) and PIXEL (pixel art) are cut together at no cost, PIXEL then snapped to its own grid and palette. STRUCTURED (bricks, planks, panels) or unset is repainted by a separately billed run. One of: ORGANIC, PIXEL, STRUCTURED
projection	enum	—	EQUIRECTANGULAR draws a 360 degree skybox: a 2:1 panorama whose left and right sides meet and whose poles are settled. Only on a model whose capabilities report `skybox` (the `create_skybox` use case); set no `tileability` with it. The size is one of the model's 2:1 presets (those carrying this projection); left unset, the largest is drawn. One of: EQUIRECTANGULAR
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.