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
subtitle_preset	string	—	Caption style, spelled exactly as one of the model's `subtitle_presets`: any other name is quoted at the default style and refused at launch. Its `subtitle_dynamic_presets` animate word by word and bill at a higher rate, so pass the same preset to the estimate. Omit for the model's default style.
subtitle_color	string	—	Caption text colour as hex (`#FFFFFF`), for models whose capabilities report `subtitle_primary_color`.
subtitle_secondary_color	string	—	Colour of the words the model emphasises, as hex, for models whose capabilities report `subtitle_secondary_color`.
subtitle_alignment	enum	—	Where the captions sit vertically, for models whose capabilities report `subtitle_alignment`. One of: top, center, bottom
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. Every set needs a front view, even a single image. One of: FRONT, LEFT, BACK, RIGHT
annotations	ImageAnnotations	—	On the init_image or a reference_image: numbered marks saying what to change where (or what to use from a reference), for models whose capabilities report visual_annotations. Each item has an id, a kind (BOX, ELLIPSE, ARROW, FREEHAND, PIN), points from (0, 0) top left to (1, 1) bottom right of the image after any crop or rotation (two corners for a box or ellipse, tail then head for an arrow, one for a pin), an intent (EDIT, REMOVE, or MOVE for an arrow whose source_id names the box or ellipse to move) and a note saying what to do there. NATIVE_BOXES models take only boxes and arrows moving a box, on the init_image. Leave color unset to have it chosen against the image.
items	ImageAnnotation[]	[]
idrequired	string1–64 chars	—
kindrequired	enum	—	One of: BOX, ELLIPSE, ARROW, FREEHAND, PIN
intent	enum	EDIT	One of: EDIT, REMOVE, MOVE
pointsrequired	ImageAnnotationPoint[]	—
note	string0–500 chars	—
color	string	—
source_id	string	—
color	string	—
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 set of sprites, a FIXED canvas with anchor BOTTOM_CENTER stands every sprite on the same point, so a set shares one sprite size. anchor BASE is only for a game tile drawn with tile_grid: it stands each tile's base on the same point, and a FIXED canvas without tile_grid refuses it. 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 resizes): after the run, Layer finds the plain band through its middle on each axis, makes the edges and centre tile (painted texture kept, light evened out), and records the insets on the file, ready for a UI kit export. Prompt for ornament in the corners only and a plain or evenly textured 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 does not resize.
parallax	ParallaxSplit	—	Split the init image into parallax layers by depth, for a side-scroller background: run it on an image eraser or inpainting model (an ERASE_OBJECT or INPAINTING use case) with the scene as init_image; that model fills in what each layer hides. `layers` (2 to 6, default 5) are cut at `cuts`, ascending nearness values in (0, 1), one fewer than the layers; omit cuts to cut at the gaps in the scene's own depth. `loop` makes every layer repeat left to right. An inpainting model given no prompt is told to continue the scenery. The output is one layered PSD, farthest layer at the bottom, with each layer's scroll speed recorded on the file, ready for export_parallax. It bills one run of the model per layer but the nearest.
layers	integer2–6	5
cuts	number[]	—
loop	boolean	false
target_language	string	—	The language a `dub_video` model speaks the clip in, as one of the ISO 639-1 codes its capabilities list under `dub_languages` (e.g. `de`). Required by those models, ignored by every other. ElevenLabs Dubbing leaves the picture and its length as they are; the HeyGen models re-sync the lips and may lengthen or shorten the clip to the new language's pace, so a dub laid back over an existing edit belongs on ElevenLabs.
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	—	Geometry compression. No current 3D model offers it, so leave it unset.
texture_resolution	enum	—	Base color texture size: RES_2K, RES_4K or RES_8K, as the model's `texture_resolutions` lists. RES_8K costs extra. One of: RES_2K, RES_4K, RES_8K
face_limit	integer	—	Face/polygon limit for 3D mesh.
workspace_idrequired	string (uuid)	—	The user's workspace id.