The Async Workflow

Sticker Maker uses an async-first architecture to handle compute-intensive operations like background removal and AI transformations without blocking your application.

How it Works

The lifecycle of a sticker generation request follows a simple three-stage pattern: Submission, Processing, and Notification.

1. Submission (HTTP 202 Accepted)

When you call the /stickers/generate endpoint, the API performs immediate validation and credit deduction. If everything is correct, it returns an HTTP 202 Accepted response immediately.

This response contains a jobId which is your unique reference for the operation.

{
  "success": true,
  "data": {
    "jobId": "job_abc123xyz",
    "status": "queued"
  }
}

2. Processing

Behind the scenes, your job is added to a high-priority queue. Our background workers pick up the job and perform the requested transformations:

• Stage: queued - Waiting for an available worker.
• Stage: processing - Active transformation (removing background, applying effects).
• Stage: completed - Job finished successfully, result is ready.
• Stage: failed - An error occurred. Credits are automatically refunded.

3. Notification & Result Retrieval

Because the processing happens asynchronously, you need a way to know when it's done. You have three powerful options:

Option A: Real-Time WebSockets (Recommended for UI)

Connect to our WebSocket endpoint for live, sub-100ms progress updates. This is perfect for showing a progress bar to your users.

// The SDK handles this automatically
client.generateSticker(request, {
  onProgress: (job) => console.log(`Progress: ${job.progress}%`),
});

Option B: Webhooks (Best for Automation)

Configure a webhook URL in your dashboard. We will send a POST request to your server the moment the job completes.

Option C: Polling (Fallback)

For simple scripts, you can periodically call the /jobs/:id endpoint until the status changes to completed.

GET /api/v1/jobs/job_abc123xyz

Why Async?

1. Responsiveness: Your user interface never hangs while waiting for an image to process.
2. Reliability: Long-running tasks are less likely to be interrupted by network timeouts.
3. Scalability: Our workers can handle massive bursts of requests without slowing down the core API.

Summary Diagram

sequenceDiagram
    participant Client
    participant API
    participant Worker

    Client->>API: POST /generate
    API-->>Client: 202 Accepted (jobId)
    API->>Worker: Enqueue Job
    Worker->>Worker: Process (5-20s)
    Worker-->>API: Job Completed
    API-->>Client: WebSocket Update / Webhook