estimate_forge_price

Estimate the Creative Units price of a forge run before executing it.

Requires either a `base_model_id` or at least one reference set; passing neither is an error.
Prices through the same reference-set translation and model selection as `execute_forge`, so
the returned price matches what the run itself charges for identical inputs. A seam repair or
background removal that runs after it as its own child run is billed separately and is not
included. Executes nothing.

For forge lifecycle guidance, call get_forge_instructions.

Parameters

Parameter	Type	Default	Description
base_model_id	string	—	Base model to price, given as an id (e.g. flux-dev), display name, or community alias. Not required when passing reference sets — a model is then auto-picked from them. Required otherwise.
reference_sets	ForgeReferenceSetInput[]	[]	Reference Sets the run will attach. Required when no base_model_id is given.
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. One of: text, image, audio, video, three_d, playable, world
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 estimate price for (1-16).
guidance_files	ForgeGuidanceFileInput[]	[]	The guidance files the execute call will pass. An upscale or a per-megapixel background removal is priced by its source file's size, and on some models an input image bills the edit rate.
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	—	The mask the execute call will pass. Some models bill a masked edit at a different rate.
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.
composition_plan	CompositionPlan	—	The track as an ordered list of sections, for models whose capabilities report `composition_plan`. Pass the same plan you intend to execute: it sets the clip's length section by section, and audio is billed per second, so an estimate without it prices a different track from the one that will run.
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
duration_seconds	number>0	—	Output length in seconds — video clip length, or audio clip length for models whose duration_seconds_min / duration_seconds_max say they take one.
prompt	string	—	Text prompt. Needed for CHARACTER_COUNT pricing models.
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`.
upscale_ratio	number	—	Upscale factor (e.g. 2.0, 4.0).
vectorize	boolean	—	Vectorize the output image.
reframe	boolean	—	Reframe/extend the image.
remove_background	boolean	—	Remove the background — pass it here whenever the execute call will, so the estimate reflects the same run.
tileability	boolean	—	Tileable output: pass it here whenever the execute call will. On a model without `native_tileability`, a STRUCTURED or unset `tile_texture` gives each output a seam-repair run that is billed separately and is not in this estimate.
tile_texture	enum	—	Pass it whenever the execute call will. STRUCTURED or unset adds a repaint run per output that this estimate does not include. One of: ORGANIC, PIXEL, STRUCTURED
projection	enum	—	EQUIRECTANGULAR for a skybox: pass it here whenever the execute call will. One of: EQUIRECTANGULAR
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 the execute call will pass — include it here for parity, so the estimated model can be checked for camera_transform support before money is spent.
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.
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
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.
workspace_idrequired	string (uuid)	—	The user's workspace id.