Async Workflow

Understand the asynchronous task pattern used by APIXO

Async Workflow

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:

POST https://api.apixo.ai/api/v1/generateTask/{model}

Request:

{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "A beautiful sunset over mountains"
  }
}

Response:

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

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

Response (in progress):

{
  "data": {
    "taskId": "task_abc123xyz",
    "state": "processing"
  }
}

Response (completed):

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

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

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

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

Async Workflow

Async Workflow

The Pattern

Step 1: Submit a Task

Step 2: Get Results

Option A: Polling (Recommended for Getting Started)

Option B: Webhooks (Recommended for Production)

Task States

Polling Best Practices

When to Use Each Approach

Next Steps

API Reference

Polling vs Webhooks

On this page