Quick start

Prerequisites

• A Civitai API token (Bearer).
• The orchestrator base URL: https://orchestration.civitai.com.

You pass the token as Authorization: Bearer <token> on every request.

1. Submit a workflow

A workflow is a list of steps. Each step has a $type (the step type) and an input. Submit the workflow to POST /v2/consumer/workflows.

POST https://orchestration.civitai.com/v2/consumer/workflows?whatif=false&wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "steps": [
    {
      "$type": "imageGen",
      "input": {
        "engine": "flux",
        "prompt": "A cat astronaut floating through neon space",
        "width": 1024,
        "height": 1024
      }
    }
  ]
}

POST/v2/consumer/workflows

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

{ "steps": [ { "$type": "imageGen", "input": { "engine": "flux", "prompt": "A cat astronaut floating through neon space", "width": 1024, "height": 1024 } } ] }

Valid JSON

Key query parameters:

Param	Default	Purpose
whatif	false	If true, validates the workflow and returns the resolved plan without executing it.
wait	0	Seconds to block waiting for completion inline; keep it below your HTTP client's timeout (step 3). 0 returns immediately with the in-flight workflow.

2. Read the response

The response is the Workflow object — the same object you get back from GetWorkflow while polling. Key fields:

{
  "id": "wf_01HXYZ...",
  "status": "succeeded",
  "steps": [
    {
      "name": "0",
      "$type": "imageGen",
      "status": "succeeded",
      "output": {
        "blobs": [
          { "id": "blob_...", "url": "https://.../signed-url" }
        ]
      }
    }
  ]
}

Statuses progress through unassigned → preparing → scheduled → processing, ending in one of the terminal states succeeded, failed, expired or canceled (see Status lifecycle).

3. Poll if you didn't wait inline

The API doesn't clamp wait, but your HTTP client likely has its own request timeout (100 s is a common default), so keep wait below it. If the connection closes before the response arrives you get no id, though the workflow keeps running and is charged; resubmitting with the same externalId returns that workflow as it currently stands (a 200 even while it is still running, so check status) instead of starting another. A workflow still running when wait elapses (most video jobs, large batches, training) comes back 202 with status: "processing"; keep its id and poll GET /v2/consumer/workflows/{workflowId} until it reaches a terminal state:

GET https://orchestration.civitai.com/v2/consumer/workflows/wf_01HXYZ...
Authorization: Bearer <your-token>

Back off between polls (suggested cadence): most image jobs finish in under 30 s, video jobs can take several minutes. Production integrations should use webhooks instead.

4. Consume outputs

Step outputs are typically blobs, each with a signed url you can fetch directly. The URL expires; see Blobs in results for refreshing it.

What's next

• Try a real recipe end-to-end: WAN video generation
• Browse all recipes: Recipes
• Go deep on the request/response shapes: API reference