---
url: /orchestration/guide/getting-started.md
---

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

# 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`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md).

```http
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
      }
    }
  ]
}
```

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](#_3-poll-if-you-didn-t-wait-inline)). `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`](https://developer.civitai.com/orchestration/reference/operations/GetWorkflow.md) while polling. Key fields:

```json
{
  "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](https://developer.civitai.com/orchestration/guide/workflows.md#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}`](https://developer.civitai.com/orchestration/reference/operations/GetWorkflow.md) until it reaches a terminal state:

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

Back off between polls ([suggested cadence](https://developer.civitai.com/orchestration/guide/results-and-webhooks.md#polling-fallback)): most image jobs finish in under 30 s, video jobs can take several minutes. Production integrations should use [webhooks](https://developer.civitai.com/orchestration/guide/results-and-webhooks.md) 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](https://developer.civitai.com/orchestration/guide/results-and-webhooks.md#blobs-in-results) for refreshing it.

## What's next

* Try a real recipe end-to-end: [WAN video generation](https://developer.civitai.com/orchestration/recipes/wan.md)
* Browse all recipes: [Recipes](https://developer.civitai.com/orchestration/recipes.md)
* Go deep on the request/response shapes: [API reference](https://developer.civitai.com/orchestration/reference.md)