--- title: "Execute inference" method: POST path: "/v2/workspaces/{workspace_id}/inferences" tags: ["Inferences"] --- # Execute inference `POST /v2/workspaces/{workspace_id}/inferences` 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). ## Path parameters - `workspace_id` string, uuid, required — Id of the workspace that owns the resource. ## Headers - `Idempotency-Key` string ## Request body - ExecuteInferenceV2Request — REST request body for executing an inference. workspace_id comes from path. - `base_model_id` string, nullable — Base model to run, as an id (e.g. flux-dev), display name, or community alias. - `reference_sets` InferenceReferenceSetInput[] — Reference sets to apply, up to 10. - `set_id` string, uuid, required — Reference set ID from GET /v2/workspaces/{workspace_id}/reference-sets. - `weight` number — Weight for the set's LoRA adapter when one applies. Ignored for sets applied as reference images or prompt text. - `modality` 'text' | 'image' | 'audio' | 'video' | 'three_d' | 'playable' - `prompt` string, nullable — Text prompt. - `negative_prompt` string, nullable — What to steer the output away from. Honored by the models whose `inference-schema` lists `negative_prompt`, and ignored by the rest. - `width` integer, nullable — Output width in pixels. If not specified, a default resolution based on the model will be applied. - `height` integer, nullable — Output height in pixels. If not specified, a default resolution based on the model will be applied. - `batch_size` integer — Number of outputs (1-16). - `num_inference_steps` integer, nullable — Number of diffusion steps. - `guidance_scale` number, nullable — Guidance scale (CFG). - `prompt_strength` number, 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. - `sharpness` number, nullable — Output sharpness. - `duration_seconds` number, nullable — Video duration in seconds. - `generate_audio` boolean, nullable — Generate audio with video. - `keep_audio` boolean, nullable — Keep audio from input video. - `fps` integer, nullable — FPS for LTX video generation (e.g. 25 or 50). - `video_effects` ForgeVideoEffectInput[] — Video effects to apply. - `type` 'general' | 'orbit_360' | 'action_run' | 'agent_reveal' | 'arc' | 'arc_left' | 'baseball_kick' | 'basketball_dunks' | 'boxing' | 'buckle_up' | 'building_explosion' | 'bullet_time' | 'car_chasing' | 'car_explosion' | 'car_grip' | 'catch' | 'catwalk' | 'crane_down' | 'crane_over_the_head' | 'crane_up' | 'crash_zoom_in' | 'crash_zoom_out' | 'dirty_lens' | 'disintegration' | 'dolly_in' | 'dolly_left' | 'dolly_out' | 'dolly_right' | 'dolly_zoom_in' | 'dolly_zoom_out' | 'double_dolly' | 'downhill_pov' | 'dutch_angle' | 'eyes_in' | 'face_punch' | 'fisheye' | 'flying' | 'focus_change' | 'fpv_drone' | 'glam' | 'handheld' | 'head_tracking' | 'hyperlapse' | 'invisible' | 'jib_down' | 'jib_up' | 'kiss' | 'lazy_susan' | 'lens_crack' | 'lens_flare' | 'levitation' | 'low_shutter' | 'melting' | 'moonwalk_left' | 'moonwalk_right' | 'mouth_in' | 'object_pov' | 'overhead' | 'push_to_glass' | 'rap_flex' | 'robo_arm' | 'set_on_fire' | 'skateboard_glide' | 'skateboarding' | 'skateboard_kickflip' | 'skateboard_ollie' | 'skate_cruise' | 'ski_carving' | 'ski_powder' | 'snorricam' | 'snowboard_carving' | 'snowboard_powder' | 'soul_jump' | 'static' | 'super_dolly_in' | 'super_dolly_out' | 'tentacles' | 'through_object_in' | 'through_object_out' | 'thunder_god' | 'tilt_down' | 'tilt_up' | 'timelapse_human' | 'timelapse_landscape' | 'turning_metal' | 'whip_pan' | 'wiggle' | 'wind_to_face' | 'yoyo_zoom' | 'zoom_in' | 'zoom_out', required - `weight` number, nullable — Effect strength (0-100). - `use_ta_pose` boolean, 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_textures` boolean, nullable — Include textures in 3D output. - `quad_mesh` boolean, nullable — Generate quad mesh. - `pbr_materials` boolean, nullable — Generate PBR materials. - `low_poly` boolean, nullable — Generate low-poly mesh. - `generate_parts` boolean, nullable — Generate separate parts. - `face_limit` integer, nullable — Face/polygon limit for 3D mesh. - `stability` number, nullable — Audio stability (0-1). - `use_speaker_boost` boolean, nullable — Boost speaker clarity. - `similarity_boost` number, nullable — Voice similarity boost (0-1). - `style_exaggeration` number, nullable — Style exaggeration (0-1). - `speed` number, nullable — Speech speed multiplier. - `upscale_ratio` number, nullable — Upscale factor (e.g. 2.0, 4.0). - `creativity` number, nullable — Creative variation strength for upscaling. - `resemblance` number, nullable — Resemblance to original for upscaling. - `vectorize` boolean, nullable — Vectorize the output image. - `remove_background` boolean, nullable — Remove background from output. - `reframe` boolean, nullable — Reframe/extend the image. - `refill` boolean, nullable — Outpaint/refill transparent areas. - `guidance_files` ForgeGuidanceFileInput[] — Reference images/files to guide generation. - `file_id` string, uuid, required — File ID of an uploaded file. - `type` 'init_image' | 'reference_image' | 'scribble' | 'color_sketch' | 'pose' | 'depth' | 'canny' | 'softedge_hed' | 'segmentation' | 'lineart' | 'face' | 'ip_adapter' | 'first_frame' | 'last_frame' | 'init_video' | 'reference_video' | 'init_mesh' | 'texture_image' | 'element_frontal_image' | 'element_reference_image' | 'element_video' | 'init_audio' | 'reference_audio', required — What a guidance file *is*. The type names the medium and the slot the file occupies. Where a model conditions on a file through a different provider input — the legacy IP-adapter path — that is its own type, because it is not the same slot. - `weight` number, nullable — Influence weight (0-1). Defaults to 0.5 for init, 1 for others. - `seed` integer — Random seed. -1 for random. - `mask` ForgeMaskInput - `file_id` string, uuid, nullable — Mask image file ID. - `for_transparency` boolean, nullable — Use transparent areas as mask. - `for_nontransparency` boolean, nullable — Use non-transparent areas as mask. - `edge_radius` integer — Mask edge blur radius in pixels. - `session_name` string, nullable — Session name. ## Response `202` Successful Response - ExecuteInferenceV2Output - `inference_id` string, uuid, required — Unique identifier for this inference run. - `status` 'in_progress' | 'complete' | 'failed' | 'cancelled' | 'deleted', required - `estimated_price_creative_units` number, nullable — Estimated price in Creative Units. - `poll_interval_seconds` integer, required — Suggested polling interval in seconds. - `created_at` string, date-time, required — Timestamp of when the run was created. - `session_id` string, uuid, nullable — Session ID the run was added to, if a session was specified. - `normalized_parameters` NormalizedInferenceParametersV2 — Inference parameters after model-specific normalization. These reflect the actual values used for generation, including model defaults applied for any parameters not explicitly set. - `width` integer, nullable — Resolved output width in pixels. - `height` integer, nullable — Resolved output height in pixels. - `batch_size` integer, nullable — Number of outputs to generate. - `num_inference_steps` integer, nullable — Resolved number of diffusion steps. - `guidance_scale` number, nullable — Resolved guidance scale. - `duration_seconds` number, nullable — Resolved video duration in seconds. - `fps` integer, nullable — Resolved FPS. - `base_model_id` string, required — Base model used for the run, resolved or auto-picked. - `reference_set_contributions` ForgeReferenceSetContribution[] — Per-set summary of what each reference set contributed. - `set_id` string, uuid, nullable — Reference Set ID this contribution belongs to, if any. - `lora_applied` boolean — True when a LoRA finetune was applied for this set. - `animation_applied` boolean — True when an animation (Meshy rigging action) finetune was applied for this set. - `voice_applied` boolean — True when a voice (ElevenLabs) finetune was applied for this set. - `mapped_asset_count` integer — Number of assets successfully mapped to guidance inputs. - `prompt_fallback_applied` boolean — True when the set fell back to prompt-only representation. - `lora_available_but_incompatible` boolean — True when SBMC has a LoRA for this set on another base model but not the one used. - `skipped_not_applicable` boolean — True when the set isn't applicable to the chosen model (its modality / applicable base models exclude it) so no LoRA or assets were applied. - `reference_sets_degraded` boolean — True when at least one attached reference set did not meaningfully contribute. The run still costs Creative Units. - `reference_sets_warning` string, nullable — Names each degraded reference set and why, or null when none is degraded. ## Other responses - `401` — Unauthenticated — missing or invalid Bearer token. - `403` — Forbidden — insufficient permissions, or the access token lacks the scope the operation requires. - `404` — Resource not found. - `409` — The request with this `Idempotency-Key` is still running — retry after the number of seconds in `Retry-After`. - `422` — Invalid input parameters, or an `Idempotency-Key` reused for a different request. - `429` — Rate limited — retry after the number of seconds in `Retry-After`. - `500` — Internal server error. --- [API](https://skmtc.dev/layer/apis/layer-rest-api.md) · [All operations](https://skmtc.dev/layer/apis/layer-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/layer/layer-rest-api/revisions/fafc779f9ba2/schema)