> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mindrift.art/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mindrift.art/_mcp/server.

# Task Lifecycle & Moderation

The Mindrift API operates asynchronously for image generation workloads and other tasks. Because deep learning synthesis requires several seconds of dedicated GPU compute, generation requests return immediately with a unique task ID, allowing your client application to track execution without holding long, fragile HTTP connections open.

This document describes the state machine governing each task, the lifecycle statuses and how automated content moderation is enforced.

---

## The Asynchronous Flow

### Submission

Your application submits a generation request with your prompt, model, resolution and parameters. The API authenticates your credentials, validates parameters against the model specification, checks your account balance and reserves a concurrency slot.

### Immediate Acknowledgment

The API responds immediately with an `HTTP 200 OK` containing a task descriptor with status queued:

```json
{
  "object": "image.generation",
  "id": "e6a0d2f8-4b1a-4638-9b88-51e8201bfb7c",
  "status": "queued",
  "model": "blackforestlabs/flux.1-schnell",
  "created_at": "2026-09-10T14:30:00.000Z"
}
```

### Status Polling

Your application queries the task endpoint at regular intervals (recommended every 1.5 to 2.5 seconds) until a terminal state (`completed` or `failed`) is reached.

---

## Task Statuses

Each generation task progresses through a defined state machine:

| Status           | State Type         | Description                                                                                                                          |
| :--------------- | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **`queued`**     | Active (In-flight) | The task has been accepted and entered the global queue. It is waiting for an available GPU worker node.                             |
| **`processing`** | Active (In-flight) | A GPU worker has claimed the task. The model weights are loaded in VRAM, and sampling/denoising is actively running.                 |
| **`completed`**  | Terminal           | Synthesis succeeded. Output images have been generated, uploaded to our high-speed CDN, and billed to your balance.                  |
| **`failed`**     | Terminal           | Synthesis failed due to a safety moderation violation or a transient technical error. An `error` object provides diagnostic details. |
| **`cancelled`**  | Terminal           | The task was terminated by the system or user prior to completion.                                                                   |

![mermaid-statuses](https://files.buildwithfern.com/visual-editor-images/docs.mindrift.art/2026-09-10T17:37:53.093Z/docs/core/task-lifecycle-moderation/mermaid-statuses.png "mermaid-statuses")

---

### Active vs. Terminal States

* **Active States (**`queued`**, **`processing`**)**: Count toward your account's **concurrency limit** (`maxConcurrentTasks` defined by your API Tier).
* **Terminal States (**`completed`**, **`failed`**, **`cancelled`**)**: Concurrency slots are immediately released upon transition to any terminal state, allowing subsequent requests to proceed.

---

## Detailed Status Descriptions

### `queued`

The initial state returned immediately after request submission. The job is registered in the database and assigned a position in the dispatch queue. Under normal traffic conditions, tasks typically spend under 1 second in this state.

### `processing`

A GPU worker has dequeued the task. The diffusion pipeline is actively running the requested number of inference steps at the target aspect ratio and resolution.

### `completed`

The task has finished successfully. The response object includes:

* `output.images`: Array of objects containing direct CDN URLs to the rendered images.
* `cost`: The exact amount deducted from your wallet balance in USD.
* `completed_at`: ISO 8601 timestamp marking completion.
* `expires_at`: ISO 8601 timestamp when the hosted files expire (`null` = kept indefinitely, see [Image Retention](/docs/core/image-retention)).
* `purged` / `purged_at`: whether and when the hosted files were deleted (manually or by expiry). A purged task returns `output.images: []` — the task itself stays queryable.

#### Completed Task Example

```json
{
  "object": "task",
  "id": "ef661acb-a140-4e68-b94f-0de439ed350d",
  "status": "completed",
  "model": "@blackforestlabs:flux-1-schnell",
  "cost": 0.0026,
  "output": {
      "images": [
          {
              "url": "https://cdn.mindrift.art/jobs/3817f808-982d-4bec-97e8-5ee91dec1381/ef661acb-a140-4e68-b94f-0de439ed350d/ef661acb-a140-4e68-b94f-0de439ed350d.webp"
          }
      ]
  },
  "error": null,
  "created_at": "2026-09-10T14:28:47.000Z",
  "completed_at": "2026-09-10T14:28:52.805Z",
  "expires_at": null,
  "purged": false,
  "purged_at": null
}
```

### `failed`

The task could not be fulfilled. The response includes an `error` object containing:

* `code`: Machine-readable error code.
* `message`: Human-readable explanation.
* `retriable`: Boolean indicating whether resubmitting the task is likely to succeed.

---

## Content Moderation & Safety

To comply with global regulatory standards and infrastructure provider policies, Mindrift enforces strict automated content moderation.

### Moderation Criteria

Prompts and generated media are evaluated against automated safety classifiers. Content falling into any of the following categories is strictly blocked:

* **Child Sexual Abuse Material (CSAM)** or exploitation of minors (zero tolerance, logged for legal reporting).
* **Explicit Not-Safe-For-Work (NSFW)**: Non-consensual sexual content, explicit pornography, or nudity on non-permissive models.
* **Extreme Violence & Gore**: Depictions of real-world torture, self-harm, suicide, or graphic physical trauma.
* **Hate Speech & Harassment**: Generating dehumanizing imagery targeting protected classes, hate symbols, or non-consensual deepfakes.

### How Moderation Manifests

When a prompt or generated image triggers our safety classifier, the task transitions to the `failed` state with the `CONTENT_MODERATION_BLOCKED` error code:

```json
{
  "object": "task",
  "id": "7a12b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  "status": "failed",
  "model": "@blackforestlabs:flux-1-schnell",
  "cost": null,
  "output": null,
  "error": {
    "code": "CONTENT_MODERATION_BLOCKED",
    "message": "Your prompt was flagged by our safety system and cannot be processed.",
    "retriable": false
  },
  "created_at": "2026-09-10T14:35:00.000Z",
  "completed_at": "2026-09-10T14:35:01.120Z"
}
```

### Key Moderation Rules

* **No Charge (**`cost: null`**)**:\
  Your wallet balance is **never charged** for tasks blocked by content moderation. Any credits reserved during submission are automatically refunded.
* **Non-Retriable (**`retriable: false`**)**:\
  Automated retries will not bypass moderation filters. Your client application should detect `retriable: false` and present feedback to the user rather than re-queueing the identical prompt.

---

## Technical Failures vs. Moderation

When inspecting a `failed` task, always evaluate the `error.retriable` flag:

| Error Code                   | Retriable | Cause                                                       | Recommended Action                                                     |
| ---------------------------- | --------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
| `CONTENT_MODERATION_BLOCKED` | `false`   | Prompt or output violated safety guidelines.                | Inform the end user to revise their prompt. Do **not** retry.          |
| `GENERATION_FAILED`          | `true`    | Transient GPU node timeout, hardware reset or network blip. | Resubmit via `POST /v1/tasks/:task_id/retry` with exponential backoff. |

### Retrying Failed Tasks

For errors where `retriable` is `true`, you can trigger an immediate re-execution using the retry endpoint without needing to reconstruct the full payload:

```http
POST https://api.mindrift.art/v1/tasks/:task_id/retry
Authorization: Bearer sk_...
```

The retry endpoint verifies your balance and active concurrency quota, resets the task to `queued` and dispatches it to a fresh worker node.

---

## Best Practices for Integration

* **Poll With Backoff**: Start polling 1.5 seconds after task creation. If the task remains `processing` after 5 seconds, increase the polling interval to 2.5 seconds to conserve your tier's polling RPM.
* **Set a Client-Side Timeout**: While GPU workers enforce internal execution timeouts (typically 60–120 seconds), your application should establish a client-side timeout threshold (e.g. 90 seconds) to handle edge-case network partitions.
* **Persist Generated Assets**: Image URLs returned in `output.images` are served via high-speed CDN. We recommend transferring production assets to your own object storage (S3, Cloudflare R2, Google Cloud Storage) if you require indefinite archival.
* **Expire When Appropriate**: Pass `ttl` (seconds, `3600`–`2592000`) at creation to auto-delete hosted files after a delay, or call `DELETE /v1/images/{id}` anytime. See [Image Retention](/docs/core/image-retention).