Migrating from v1

Welcome to the next generation of sticker creation! Sticker Maker API v2.0 is a complete ground-up redesign focused on high-performance, scalability, and developer experience.

This guide will help you transition your existing v1.0 integrations to our new async-first architecture.

Why Upgrade?

v2.0 introduces several major improvements over the legacy v1.0 API:

• Non-blocking Operations: No more waiting for HTTP connections to finish processing.
• Improved Reliability: Long-running jobs are handled by a robust queue system.
• Better Security: Authorization headers and webhook signatures protect your data.
• Credit Transparency: Know exactly what each operation costs before you commit.

1. Sync vs. Async Workflow

In v1.0, requests were synchronous—you sent an image and waited for the processed file in the response. In v2.0, all media processing is asynchronous.

Comparison

Code Example

// Sync: Waiting for the file to be returned directly
const response = await fetch('https://api.stickermaker.dev/v1/generate', {
  method: 'POST',
  body: JSON.stringify({ image_url: '...' })
});

const blob = await response.blob();
showSticker(URL.createObjectURL(blob));

// Async: Get a jobId, then track progress
const response = await fetch('https://api.stickermaker.dev/api/v1/stickers/generate', {
  method: 'POST',
  headers: { 
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json' 
  },
  body: JSON.stringify({ 
    source: { type: 'image', image: { url: '...' } },
    processing: { image: { removeBackground: 'hq' } },
    output: { format: 'webp', size: 512 }
  })
});

const { data } = await response.json();
console.log(`Job created: ${data.jobId}`);

// Use the SDK to track completion automatically
// or poll the GET /api/v1/jobs/:id endpoint

2. Authentication

We have moved from a custom header to the industry-standard Authorization: Bearer format.

• Legacy v1.0: X-API-Key: your_key
• Modern v2.0: Authorization: Bearer your_key

POST /v1/generate
X-API-Key: sk_test_12345

POST /api/v1/stickers/generate
Authorization: Bearer sk_test_12345

3. Response Format

All v2.0 responses are wrapped in a standardized JSON envelope to ensure consistent error handling and metadata access.

// Raw response or inconsistent structure
{
  "url": "https://cdn.com/sticker.webp",
  "width": 512
}

// Standardized envelope
{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "queued",
    "estimatedTime": 15,
    "creditsUsed": 5
  }
}

4. Webhooks Security

Webhook notifications in v2.0 include a security signature to prevent spoofing. You must verify this signature using your Webhook Secret.

• v1.0: No signature verification.
• v2.0: Verify X-Sticker-Signature using HMAC-SHA256.

// v2.0 Signature Verification Example (Node.js)
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return signature === digest;
}

5. Credit-Based Billing

Legacy v1.0 used simple request counting. v2.0 introduces a granular Credit System.

• v1.0: 1 Request = 1 Operation.
• v2.0: Different operations cost different amounts of credits (e.g., HQ background removal costs more than standard).

Credits are deducted at the moment of Submission and automatically refunded if a job fails due to a system error.

Migration Checklist

• Update API base URL to https://api.stickermaker.dev/api/v1
• Switch X-API-Key header to Authorization: Bearer
• Update request bodies to the new nested structure (source, processing, output)
• Implement async handling (Polling or Webhooks)
• (Optional) Migrate to the Official JavaScript SDK for the best experience