> ## 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: Submit Tasks, Poll Status & Get Results

> Understand APIXO's asynchronous task pattern: submit a generation task, poll its status or use webhooks, and retrieve result URLs.

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](/docs/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="/docs/models">
    Understand the async API pattern for image, video, and audio models
  </Card>

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.