Inferences

Execute inference

Start an AI inference (image, video, 3D, or audio). Pass a base_model_id, at least one entry in reference_sets, or both — with reference sets alone a compatible base model is picked from them. Returns immediately with an ID. Poll with GET /v2/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.

Reference-set errors: REFERENCE_SET_NOT_FOUND (404 — unknown, deleted, or outside this workspace's reach), NO_COMPATIBLE_MODEL (422 — no enabled base model can apply these sets), REFERENCE_SET_REQUIRED (422 — the chosen model needs an applicable set), REFERENCE_SET_CONFLICT (422 — two sets supply the same singular adapter), and INPUT_FILE_REQUIRED (422 — the sets select an edit-only model with no asset to edit).

post/v2/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

base_model_idstring nullable

Base model to run, as an id (e.g. flux-dev), display name, or community alias.

promptstring nullable

Text prompt.

negative_promptstring nullable

What to steer the output away from. Honored by the models whose inference-schema lists negative_prompt, and ignored by the rest.

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 inference 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.

base_model_idstring required

Base model used for the run, resolved or auto-picked.

reference_sets_degradedboolean

True when at least one attached reference set did not meaningfully contribute. The run still costs Creative Units.

reference_sets_warningstring nullable

Names each degraded reference set and why, or null when none is degraded.

Changes

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