Inferences

Execute inference

Start an AI inference (image, video, 3D, or audio). Returns immediately with an ID. Poll with GET /workspaces/{workspace_id}/inferences/{inference_id} for results. Creative Units are not checked here: an underfunded workspace is still accepted and the run then reports FAILED with error_code INSUFFICIENT_BALANCE. Use the estimate endpoint's has_sufficient_creative_units to check before submitting.

post/v1/workspaces/{workspace_id}/inferences

Path parameters

workspace_idstring uuid required

Id of the workspace that owns the resource.

Headers

Idempotency-Keystring

Opaque key making this request safe to retry. The first request with a given key executes; a later request with the same key returns that first response with Idempotent-Replayed: true instead of executing again. The key covers the method, path, query, and body it was first used with; reusing it for a different request is rejected with 422. Replayable for 24 hours.

Request body

model_idstring uuid required

Model/style ID to use for generation.

weightnumber

Style/LoRA strength applied to the model. 1.0 = as trained; lower weakens, higher over-applies the style. Only affects LoRA/adapter-backed styles; ignored for models without a trainable adapter.

promptstring nullable

Text prompt.

widthinteger nullable

Output width in pixels. If not specified, a default resolution based on the model will be applied.

heightinteger nullable

Output height in pixels. If not specified, a default resolution based on the model will be applied.

batch_sizeinteger

Number of outputs (1-16).

num_inference_stepsinteger nullable

Number of diffusion steps.

guidance_scalenumber nullable

Guidance scale (CFG).

prompt_strengthnumber nullable

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'low' | 'medium' | 'high' nullable

Quality level: low, medium, or high.

sharpnessnumber nullable

Output sharpness.

duration_secondsnumber nullable

Video duration in seconds.

generate_audioboolean nullable

Generate audio with video.

keep_audioboolean nullable

Keep audio from input video.

fpsinteger nullable

FPS for LTX video generation (e.g. 25 or 50).

use_ta_poseboolean nullable

Deprecated: use pose_mode. Legacy rig-ready-pose toggle for 3D.

pose_mode'A_POSE' | 'T_POSE'

Canonical rest pose a character-mesh model is asked to generate in. A_POSE places the arms angled down at roughly 45°; T_POSE holds them straight out to the sides. Only meaningful for models that advertise the pose_modes capability (e.g. Meshy V7).

Deliberately a light top-level module (like base_model_id), NOT under pkg.models.inference: the Blueprint definition layer registers this as a BlueprintType and migrates legacy node ports, and must do so without pulling in the heavy pkg.models.inference package, which would perturb the Temporal workflow-sandbox import graph and split pydantic class identity.

include_texturesboolean nullable

Include textures in 3D output.

quad_meshboolean nullable

Generate quad mesh.

pbr_materialsboolean nullable

Generate PBR materials.

low_polyboolean nullable

Generate low-poly mesh.

generate_partsboolean nullable

Generate separate parts.

face_limitinteger nullable

Face/polygon limit for 3D mesh.

stabilitynumber nullable

Audio stability (0-1).

use_speaker_boostboolean nullable

Boost speaker clarity.

similarity_boostnumber nullable

Voice similarity boost (0-1).

style_exaggerationnumber nullable

Style exaggeration (0-1).

speednumber nullable

Speech speed multiplier.

upscale_rationumber nullable

Upscale factor (e.g. 2.0, 4.0).

creativitynumber nullable

Creative variation strength for upscaling.

resemblancenumber nullable

Resemblance to original for upscaling.

vectorizeboolean nullable

Vectorize the output image.

remove_backgroundboolean nullable

Remove background from output.

reframeboolean nullable

Reframe/extend the image.

refillboolean nullable

Outpaint/refill transparent areas.

seedinteger

Random seed. -1 for random.

session_namestring nullable

Session name.

Response

Successful Response

inference_idstring uuid required

Unique identifier for this forge run.

status'in_progress' | 'complete' | 'failed' | 'cancelled' | 'deleted' required

estimated_price_creative_unitsnumber nullable

Estimated price in Creative Units.

poll_interval_secondsinteger required

Suggested polling interval in seconds.

created_atstring date-time required

Timestamp of when the run was created.

session_idstring uuid nullable

Session ID the run was added to, if a session was specified.

Changes

No recorded changes to this endpoint across all 1 revision of this API.