Async Workflow: Submit Tasks, Poll Status & Get Results

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

Next Steps

Generation API Overview

Understand the async API pattern for image, video, and audio models

Generate Task

Submit a generation task and receive a task ID

Polling vs Webhooks

Deep dive into both approaches

​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