Skip to main content
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: 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
  }
}
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

StateDescription
pendingTask queued, waiting to start
processingTask is being processed
successTask completed successfully
failedTask 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
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

ApproachBest For
PollingSimple integrations, client-side apps, testing
WebhooksProduction servers, real-time apps, high volume

​
Next Steps

API Reference

Detailed endpoint documentation

Polling vs Webhooks

Deep dive into both approaches