AI Sticker Generator API v1 · developer guide

AI Sticker Generator — Backend API

REST API for the AI Sticker Generator mobile app. All paths below are relative to the base URL.

Base URL
API prefix/api — every path below is relative to the base URL
FormatJSON (application/json), except from-image which is multipart/form-data

Conventions & authentication

Response envelope

// success
{ "success": true, "message": "Sticker job created successfully", "data": { ... } }
// error
{ "success": false, "code": "FREE_QUOTA_EXHAUSTED", "message": "…", "data": { ... optional } }

Who is calling? (bearer token or device)

  • Registered user: Authorization: Bearer <accessToken>. Access tokens are short-lived (JWT_EXPIRES_IN); renew with POST /api/auth/refresh.
  • Anonymous device: X-Device-Id: <installId> after calling POST /api/devices/register. Only the sticker, quota and asset endpoints accept it, and it can only spend the device's small free quota.
  • If both headers are sent, the token wins. Subscription, payment and account endpoints require a bearer token — a device ID can never change them.

Other headers

  • Idempotency-Key: <8-128 chars> on from-image/from-prompt — generate one UUID per user action and reuse it on retries to avoid double charges.
  • X-Request-Id is returned on every response; include it in bug reports.

Status codes

200/201/202OK / created / accepted (async job queued)
400Malformed JSON, invalid/expired reset token or webhook signature
401Missing/invalid token, device header, or asset link
403Quota exhausted / insufficient credits / blocked device
404Not found (also used for resources owned by someone else)
409Duplicate email, idempotency key reused with a different body
413Upload or body too large
422Validation failed, bad image, content rejected by safety checks
429Rate limit, too many active jobs, account temporarily locked
500/501/503Server error / feature not configured (payments) / dependency unavailable

API reference