> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Workflow

> Understand the asynchronous task pattern used by APIXO

APIXO uses an asynchronous pattern for all generation tasks. This design handles the reality that AI generation takes time—from a few seconds for images to several minutes for videos.

## The Pattern

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Submit    │────▶│  Poll or    │────▶│   Retrieve  │
│   Task      │     │  Callback   │     │   Results   │
└─────────────┘     └─────────────┘     └─────────────┘
      │                   │                   │
      ▼                   ▼                   ▼
   taskId            state check          resultUrls
```

## Step 1: Submit a Task

Send a `POST` request to create a generation task:

```bash theme={null}
POST https://api.apixo.ai/api/v1/generateTask/{model}
```

**Request:**

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A beautiful sunset over mountains"
  }
}
```

**Response:**

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_abc123xyz"
  }
}
```

The API immediately returns a `taskId`. The actual generation happens in the background.

## Step 2: Get Results

You have two options to receive results:

### Option A: Polling (Recommended for Getting Started)

Periodically check the task status:

```bash theme={null}
GET https://api.apixo.ai/api/v1/statusTask/{model}?taskId={taskId}
```

**Response (in progress):**

```json theme={null}
{
  "data": {
    "taskId": "task_abc123xyz",
    "state": "processing"
  }
}
```

**Response (completed):**

```json theme={null}
{
  "data": {
    "taskId": "task_abc123xyz",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://cdn.apixo.ai/...\"]}",
    "costTime": 12500
  }
}
```

### Option B: Webhooks (Recommended for Production)

Provide a `callback_url` when submitting:

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhook/apixo",
  "input": { ... }
}
```

APIXO will `POST` the result to your URL when the task completes.

See [Webhooks](/api-reference/webhooks) for implementation details.

## Task States

| State        | Description                   |
| ------------ | ----------------------------- |
| `pending`    | Task queued, waiting to start |
| `processing` | Task is being processed       |
| `success`    | Task completed successfully   |
| `failed`     | Task failed (check `failMsg`) |

## Polling Best Practices

1. **Start with 3-5 second intervals** for most tasks
2. **Use exponential backoff** for long-running tasks (videos)
3. **Set a maximum timeout** (e.g., 5 minutes)
4. **Handle failures gracefully** with retry logic

```javascript theme={null}
const pollWithBackoff = async (taskId, maxWait = 300000) => {
  let interval = 3000; // Start at 3s
  const startTime = Date.now();
  
  while (Date.now() - startTime < maxWait) {
    const result = await checkStatus(taskId);
    
    if (result.state === 'success') return result;
    if (result.state === 'failed') throw new Error(result.failMsg);
    
    await sleep(interval);
    interval = Math.min(interval * 1.5, 30000); // Max 30s
  }
  
  throw new Error('Timeout waiting for result');
};
```

## When to Use Each Approach

| Approach     | Best For                                        |
| ------------ | ----------------------------------------------- |
| **Polling**  | Simple integrations, client-side apps, testing  |
| **Webhooks** | Production servers, real-time apps, high volume |

## Next Steps

<CardGroup>
  <Card title="Generation API Overview" href="/models">
    Understand the async API pattern for image, video, and audio models
  </Card>

  <Card title="Generate Task" href="/api-reference/generate-task">
    Submit a generation task and receive a task ID
  </Card>

  <Card title="Polling vs Webhooks" href="/guides/polling-vs-webhooks">
    Deep dive into both approaches
  </Card>
</CardGroup>