Task Lifecycle & Moderation | Mindrdift

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:

{
  "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.

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).
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

{
  "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:

{
  "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:

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.