---
url: /orchestration/reference/operations/InvokeCustomComfyStepTemplate.md
description: 'POST /v2/consumer/recipes/customComfy — CustomComfy'
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# CustomComfy

`POST https://orchestration.civitai.com/v2/consumer/recipes/customComfy`

Operation `InvokeCustomComfyStepTemplate` · Recipes · Civitai Orchestration API, generated from the published OpenAPI spec ([v2-consumers.json](https://developer.civitai.com/openapi/v2-consumers.json)); the interactive HTML page is this URL without `.md`.

Submit a raw ComfyUI workflow graph for execution. Every resource the workflow uses, including <c>comfy:nodepack</c> URNs
/// for custom nodes, must be declared in <c>resources</c>; the orchestrator does not scan the workflow. Billed after execution
/// on actual ComfyUI runtime; infra failures don't charge.

## Authentication

Send `Authorization: Bearer <token>` (the spec's `ApiKey` scheme); this operation documents `401 Unauthorized` for a missing or invalid token. See [Authentication](https://developer.civitai.com/orchestration/guide/authentication.md).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `experimental` | query | boolean | no |  |
| `allowMatureContent` | query | boolean | no |  |
| `whatif` | query | boolean | no |  |
| `ephemeral` | query | boolean | no |  |
| `tier` | query | `WorkflowTier` (one of `paid`, `free`) | no | How a workflow is paid for. |

## Request body

Optional. Content types: `application/json`, `text/json`, `application/*+json`.

Schema `CustomComfyInput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `resources` | array of string | yes | All resources the workflow needs as AIR URNs, including `comfy:nodepack` URNs for runtime-installable custom nodes. Anything the workflow references that is not listed here fails at load time inside ComfyUI. (minItems `1`) |
| `workflow` | any | yes | The raw ComfyUI workflow graph. Forwarded opaquely to the worker; the orchestrator does not inspect or validate node contents. |
| `trace` | `TraceMode` (one of `none`, `logs`, `binary`) | yes | How much of the ComfyUI `/ws` activity the worker records to a streaming blob the consumer can tail live (URL on `output.traceUrl`). None (default) records nothing. |
| `sessionId` | string, nullable | no | When set, the scheduler prefers a worker that already holds this session's ComfyUI container. Null = no preference. |
| `comfyImage` | string, nullable | no | Custom comfy container image as an `urn:air:oci:image:<source>:<repo>@<version\|sha256:…>` AIR. Null = worker default. (pattern `^(?:urn:)?(?:air:)?(?:(?<ecosystem>[a-zA-Z0-9_\-\/]+):)?(?:(?<type>[a-zA-Z0-9_\-\/]+):)?(?<source>[a-zA-Z0-9_\-\/]+):(?<id>[a-zA-Z0-9_\-\/\.]+)(?:@(?<version>[a-zA-Z0-9_\-\/.=,%+:]+))?(?:\.(?<format>[a-zA-Z0-9_\-]+))?$`) |
| `minVramGb` | integer (int32), nullable | no | Minimum GPU VRAM (GB) the claiming worker must report. Null = any comfy-capable worker. |
| `useSageAttention` | boolean, nullable | no | Launches ComfyUI with `--use-sage-attention`. Null/false = the image's default (off for the cloud/slim images). |
| `minimumDurationSeconds` | integer (int32), nullable | no | Submit-time affordability gate: the workflow is rejected (400) unless the user can afford at least this many seconds of generation. Null = no gate; the live-balance guard still cancels mid-run if the balance goes negative. |

## Responses

### 200 OK

Content type: `application/json`.

Schema `CustomComfyOutput`.

| Field | Type | Required | Description |
|---|---|---|---|
| `blobs` | array of `Blob` | yes |  |
| `traceUrl` | string (uri), nullable | no | URL of the recorded ComfyUI `/ws` trace (`.txt` log or `.bin` recording per the requested `trace` mode), tailable live while the job runs. Null when tracing wasn't requested. |
| `tempBlobs` | array of `Blob` | yes |  |
| `usage` | `CustomComfyUsage` | no |  |

### 400 Bad Request

Content type: `application/json`.

Schema `ProblemDetails`.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string, nullable | no |  |
| `title` | string, nullable | no |  |
| `status` | integer (int32), nullable | no |  |
| `detail` | string, nullable | no |  |
| `instance` | string, nullable | no |  |

### 401 Unauthorized

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.

### 403 Forbidden

Content type: `application/json`.

Schema `ProblemDetails` — fields as listed above.