Simulations

Type: Reference · Audience: Pipeline TDs, researchers, automation builders

jobType: "simulation" covers two distinct compute shapes. Which one a simulator uses is not a client choice — it is determined by whether the solver's frames are independent of each other.

Shape	Simulators	Task contract	Independence
Parallel task-array	swan, wavewatch3 (plus the molecular-docking/sequence-search simulators — see Submitting jobs)	taskCount independent tasks, 1..taskCount	Each task is a self-contained case/variant; tasks never share state
Sequential (Cloud Bake)	blender-fluid, blender-cloth, blender-rigidbody, blender-geonodes; houdini-fluid, houdini-pyro, houdini-rbd, houdini-vellum, houdini-crowds (gated, see below)	frameStart..frameEnd, cooked by one task in order	Frame N's solver state depends on frame N-1 — cannot be split across independent tasks

Submitting a stateful (sequential-only) simulator with taskCount > 1 is rejected with 422 STATEFUL_SIM_NOT_PARALLELIZABLE: a parallel fan-out would re-cook each task from frame 1 with no prior state and silently produce wrong physics, so the API refuses instead of guessing.

---

Cloud Bake is a gated preview

Sequential submission is dark by default. Until your deployment enables it, submitting blender-fluid/blender-cloth/blender-rigidbody/ blender-geonodes (or a houdini-* simulator) returns 422 CLOUD_BAKE_DISABLED. Bake locally and attach the resulting cache to a render job in the meantime. houdini-* simulators carry a second, independent gate (HOUDINI_SIM_UNAVAILABLE) because hython/hbatch requires a Houdini Engine/FX licence that a render-only licence does not cover.

---

Parallel simulations

Required fields: sceneFile (the input dataset), simulator, taskCount (1–10,000). Each task runs independently; the input bundle is expected to expose one case/variant per task index (see Submitting jobs for the SWAN/WAVEWATCH III bundle layout and the BLAST/AutoDock Vina molecular examples).

curl -X POST https://kinocloud.io/api/v1/jobs/submit \
  -H "Authorization: Bearer kc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "simulation",
    "sceneFile": "uploads/8f3c.../swan-cases.tar",
    "simulator": "swan",
    "taskCount": 24,
    "jobName": "offshore-wind-swan-ensemble"
  }'

---

Sequential simulations (Cloud Bake)

A stateful simulator submits as one sequential task that cooks the full frame range in order — the shape a Mantaflow/point-cache bake or a Houdini DOP solve actually requires.

Required fields: sceneFile, a stateful simulator, frameStart + frameEnd (the bake range). taskCount must be 1 or absent. Optional metadata.bakeWallClockCapMinutes sets the wall-clock ceiling for the bake (15–1440 minutes, default 240, clamped to the deployment's configured maximum).

curl -X POST https://kinocloud.io/api/v1/jobs/submit \
  -H "Authorization: Bearer kc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "simulation",
    "sceneFile": "uploads/8f3c.../ocean_sim.blend",
    "simulator": "blender-fluid",
    "frameStart": 1,
    "frameEnd": 250,
    "metadata": { "bakeWallClockCapMinutes": 180 },
    "jobName": "ocean-domain-bake-v3"
  }'

Billing: cap-as-hold

The bake is priced and held at the wall-clock cap, not at actual usage:

1. The quote prices the full bakeWallClockCapMinutes on the bake compute SKU, and the credit hold reserves that amount up front — the cap is a hard ceiling on what the job can ever cost you.
2. The task is force-killed at the cap (timeout(1), SIGTERM then SIGKILL after a 60s grace period) — it cannot run, and therefore cannot bill, past what was quoted and held.
3. Settlement bills the actual provider-metered runtime, which is less than or equal to the held amount. You are never charged more than the cap, and typically less if the bake finished early.

If the cap is reached before the bake finishes, the task ends non-zero and the job reports failed — but the partial resumable cache is preserved (Blender's own resumable point-cache / fluid-domain resume). Resubmit with a higher bakeWallClockCapMinutes to continue baking from where it stopped, rather than restarting from frame 1.

Output-size ceiling

The bake script measures the output directory after the solve (or after the cap kills it) and fails the task if it exceeds the deployment's output ceiling (CLOUD_BAKE_MAX_OUTPUT_GB, default 256 GB) — checked before the wall-clock-cap outcome, so an oversized cache fails the task even if the cap was never reached. This is a new class of limit: every pre-existing ceiling in the API is input-side; simulation caches are the first workload where the output can be the big number.

---

Error codes

code	HTTP	Meaning
UNSUPPORTED_SIMULATOR	422	simulator is not on the allowlist
TASK_COUNT_OUT_OF_RANGE	400	Parallel job: taskCount is missing or exceeds the maximum (10,000)
STATEFUL_SIM_NOT_PARALLELIZABLE	422	A stateful simulator (blender-*, houdini-*) was submitted with taskCount > 1; resubmit with taskCount 1 or omitted as a sequential bake
CLOUD_BAKE_DISABLED	422	Sequential (Cloud Bake) submission attempted while the gated preview is off on this deployment
HOUDINI_SIM_UNAVAILABLE	422	A houdini-* simulator was submitted while the Houdini Engine/FX licence gate is off (independent of CLOUD_BAKE_DISABLED)
BAKE_FRAME_RANGE_REQUIRED	400	Sequential bake is missing frameStart and/or frameEnd
BAKE_FRAME_RANGE_INVALID	400	frameEnd is before frameStart, or the range exceeds 300,000 frames
CLOUD_BAKE_FLEET_UNAVAILABLE	503	No bake compute pool is configured on this deployment — fails before any credit hold is placed
COST_LIMIT_EXCEEDED	422	The estimated cost (the full wall-clock cap, for a sequential bake) exceeds the per-job ceiling; see maxAllowed in the response

These use the same envelope as every other endpoint — see Errors & rate limits for the full catalogue and the general error/rate-limit conventions.

---

See also

• Submitting jobs — job lifecycle, cost estimation, upload flow, idempotency, polling
• Errors & rate limits — the full error code catalogue