# 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 | | ------------------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 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. 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 | — | 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 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 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 | — | 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. | | 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. |