Polling vs Webhooks

APIXO offers two ways to receive task results: polling (async mode) and webhooks (callback mode). This guide helps you choose the right approach and implement it effectively.

Quick Comparison

Aspect	Polling (Async)	Webhooks (Callback)
Setup	Simple	Requires public endpoint
Real-time	Near real-time	Instant
API Calls	Multiple per task	One per task
Best For	Development, client apps	Production servers
Infrastructure	None	HTTPS endpoint

When to Use Polling

Choose polling when:

Building client-side applications
Prototyping or testing
You don’t have a public server
Processing low volume of tasks

Basic Polling Implementation

async function pollForResult(model, taskId, apiKey) {
  const interval = 3000; // 3 seconds
  const maxAttempts = 60;
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
    
    await new Promise(r => setTimeout(r, interval));
  }
  
  throw new Error('Timeout');
}

Exponential Backoff

For better efficiency, use exponential backoff:

async function pollWithBackoff(model, taskId, apiKey) {
  let interval = 3000; // Start at 3s
  const maxInterval = 30000; // Max 30s
  const maxTime = 300000; // 5 min timeout
  let elapsed = 0;
  
  while (elapsed < maxTime) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${model}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    
    const { data } = await response.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
    
    await new Promise(r => setTimeout(r, interval));
    elapsed += interval;
    interval = Math.min(interval * 1.5, maxInterval);
  }
  
  throw new Error('Timeout');
}

Recommended Intervals by Model Type

Model Type	Initial Wait	Poll Interval	Max Wait
Image (fast)	5s	3s	2 min
Image (quality)	10s	5s	3 min
Video	60s	15s	10 min
Audio	30s	10s	5 min

When to Use Webhooks

Choose webhooks when:

Running a production server
Processing high volume of tasks
Need real-time notifications
Want to minimize API calls

Webhook Setup

1. Create an endpoint:

Express.js
FastAPI
Next.js

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/apixo', (req, res) => {
  const { taskId, state, resultJson, failCode, failMsg } = req.body.data;
  
  if (state === 'success') {
    const urls = JSON.parse(resultJson).resultUrls;
    console.log('Generated:', urls);
    // Process your images/videos
  } else if (state === 'failed') {
    console.error(`Task ${taskId} failed: ${failCode}`);
  }
  
  res.status(200).send('OK');
});

app.listen(3000);

from fastapi import FastAPI, Request
import json

app = FastAPI()

@app.post('/webhook/apixo')
async def handle_webhook(request: Request):
    body = await request.json()
    data = body['data']
    
    if data['state'] == 'success':
        urls = json.loads(data['resultJson'])['resultUrls']
        print(f"Generated: {urls}")
    elif data['state'] == 'failed':
        print(f"Task {data['taskId']} failed: {data['failCode']}")
    
    return {'status': 'ok'}

// app/api/webhook/apixo/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { taskId, state, resultJson, failCode } = body.data;
  
  if (state === 'success') {
    const urls = JSON.parse(resultJson).resultUrls;
    console.log('Generated:', urls);
  } else if (state === 'failed') {
    console.error(`Task ${taskId} failed: ${failCode}`);
  }
  
  return NextResponse.json({ status: 'ok' });
}

2. Submit task with callback:

const response = await fetch('https://api.apixo.ai/api/v1/generateTask/nano-banana', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    request_type: 'callback',
    callback_url: 'https://your-domain.com/webhook/apixo',
    input: {
      mode: 'text-to-image',
      prompt: 'A beautiful landscape',
    },
  }),
});

Webhook Requirements

Must be publicly accessible via HTTPS
Must respond with HTTP 200 within 30 seconds
Should handle duplicate deliveries (use taskId for idempotency)

Retry Policy

If your webhook fails:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes

After 3 failed attempts, the webhook is abandoned. You can still query via the status endpoint.

Hybrid Approach

For maximum reliability, combine both approaches:

class TaskManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.pendingTasks = new Map();
  }
  
  async submit(model, input, callbackUrl = null) {
    const response = await fetch(
      `https://api.apixo.ai/api/v1/generateTask/${model}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          request_type: callbackUrl ? 'callback' : 'async',
          callback_url: callbackUrl,
          input,
        }),
      }
    );
    
    const { data } = await response.json();
    
    if (!callbackUrl) {
      // Fallback to polling if no webhook
      return this.poll(model, data.taskId);
    }
    
    // Track task for webhook
    this.pendingTasks.set(data.taskId, { model, status: 'pending' });
    return data.taskId;
  }
  
  handleWebhook(body) {
    const { taskId, state, resultJson, failMsg } = body.data;
    
    if (state === 'success') {
      this.pendingTasks.delete(taskId);
      return JSON.parse(resultJson).resultUrls;
    }
    
    if (state === 'failed') {
      this.pendingTasks.delete(taskId);
      throw new Error(failMsg);
    }
  }
  
  async poll(model, taskId) {
    // Fallback polling implementation
    return pollWithBackoff(model, taskId, this.apiKey);
  }
}

Local Development with ngrok

For testing webhooks locally:

# Install ngrok
npm install -g ngrok

# Start your local server
node server.js  # runs on port 3000

# Tunnel to local server
ngrok http 3000
# Returns: https://abc123.ngrok.io

# Use ngrok URL as callback_url

Summary

Scenario	Recommendation
Development / Testing	Polling
Client-side app	Polling
Production backend	Webhooks
High volume	Webhooks
Maximum reliability	Hybrid (webhooks + polling fallback)

Start with polling for simplicity, then migrate to webhooks as your application scales.

Getting Started

Concepts

API Reference

Models

Guides

Polling vs Webhooks

Quick Comparison

When to Use Polling

Basic Polling Implementation

Exponential Backoff

Recommended Intervals by Model Type

When to Use Webhooks

Webhook Setup

Webhook Requirements

Retry Policy

Hybrid Approach

Local Development with ngrok

Summary

Getting Started

Concepts

API Reference

Models

Guides

​Quick Comparison

​When to Use Polling

​Basic Polling Implementation

​Exponential Backoff

​Recommended Intervals by Model Type

​When to Use Webhooks

​Webhook Setup

​Webhook Requirements

​Retry Policy

​Hybrid Approach

​Local Development with ngrok

​Summary

Quick Comparison

When to Use Polling

Basic Polling Implementation

Exponential Backoff

Recommended Intervals by Model Type

When to Use Webhooks

Webhook Setup

Webhook Requirements

Retry Policy

Hybrid Approach

Local Development with ngrok

Summary