API Documentation

Go from zero to your first processed image in under two minutes. OptikAPI speaks plain REST: send multipart/form-data, get back JSON with your image as a Base64 data URL.

curl -X POST https://your-domain.com/api/v1/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product.jpg"

{
  "job_id": "job_9f3a2c1e",
  "status": "succeeded",
  "output_url": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "reserved_credits": 1
}

All API requests are authenticated with a Bearer token. Include your secret API key in the Authorization header of every request.

Authorization: Bearer optk_your_api_key_here

API keys start with optk_ and can be created or revoked at any time from the API Keys dashboard. Revoking a key takes effect immediately.

Removes the background from an image with high precision — clean edges around hair, glass, and complex shapes. Costs 1 credit per successful image and returns a transparent PNG as a Base64 data URL.

Request Body

Format: multipart/form-data

Response (200 OK)

Code Examples

curl -X POST https://your-domain.com/api/v1/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

# Response (200):
# {
#   "job_id": "job_9f3a2c1e",
#   "status": "succeeded",
#   "output_url": "data:image/png;base64,...",
#   "reserved_credits": 1
# }

An all-in-one pipeline: removes the background, centers the product with optical (not geometric) alignment, applies consistent margins, and places it on a clean white canvas. Costs 2 credits per successful image. Output is a 2000×2000 white-background image returned as a Base64 data URL.

Request Body

Format: multipart/form-data

Response (200 OK)

The processor returns the prepared image. Product classification, fill ratio, and centering measurements are not included in the response.

Code Examples

curl -X POST https://your-domain.com/api/v1/prepare-product \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/product.jpg"

# Response (200):
# {
#   "job_id": "job_7b1d4e8a",
#   "status": "succeeded",
#   "output_url": "data:image/png;base64,...",
#   "reserved_credits": 2
# }

Returns the current credit balance of the authenticated account. Use it to monitor usage and trigger alerts before you run out.

curl https://your-domain.com/api/v1/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response (200):
# {
#   "credits": {
#     "total": 500,
#     "available": 492,
#     "reserved": 8
#   }
# }

Retrieves the status and result of a job by its ID. Image endpoints are synchronous — they return the final image immediately — so this endpoint is mainly useful for auditing, debugging, and checking a request that is still processing.

curl https://your-domain.com/api/v1/jobs/job_7b1d4e8a \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response (200):
# {
#   "job_id": "job_7b1d4e8a",
#   "status": "succeeded",
#   "service_type": "prepare-product",
#   "created_at": "2026-09-19T10:24:11.000Z",
#   "output_url": "data:image/png;base64,...",
#   "credits_consumed": 2
# }

Rate limits

The API allows 300 requests per minute per account across all /api/v1/* endpoints. Exceeding it returns 429 RATE_LIMITED with a Retry-After header telling you exactly when to try again.

Fair-use concurrency queue

Each account may run up to 3 image jobs concurrently. Requests beyond that wait in a FIFO line for up to ~20 seconds instead of failing, which makes bursty catalog imports work smoothly without any client-side throttling.

If the waiting line is full or a request waits too long, the API responds with 429 and one of two error codes — always with a Retry-After header:

OptikAPI uses standard HTTP status codes. Every error response has the same shape — a machine-readable code and a human-readable message:

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient credits"
  }
}

Retrying safely

• On 429, always wait at least the Retry-After seconds before retrying.
• On 500 and network errors, use exponential backoff with jitter (e.g. 1s, 2s, 4s, 8s — max 5 attempts).
• Never retry 400, 401, 402, 413, or 422 without fixing the request first.

async function processWithRetry(form, attempt = 0) {
  const res = await fetch('https://your-domain.com/api/v1/remove-background', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    body: form,
  });

  if (res.ok) return res.json();

  const retryable = res.status === 429 || res.status >= 500;
  if (retryable && attempt < 5) {
    const retryAfter = Number(res.headers.get('retry-after') || 0);
    const backoff = Math.min(2 ** attempt + Math.random(), 30);
    await new Promise(r => setTimeout(r, Math.max(retryAfter, backoff) * 1000));
    return processWithRetry(form, attempt + 1);
  }

  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

Working with Base64 output

• Split on the first comma only: output_url.split(",")[1] — never strip the data:image/png;base64, prefix with fixed string lengths.
• For large batches, stream results to disk or object storage instead of holding them in memory.

Getting the best results

• Use the highest-resolution source you have (the model handles up to 10MB comfortably).
• Well-lit products with clear contrast against their background produce the cleanest edges.
• For catalog work, always use prepare-product — consistent 2000×2000 canvases make listings look uniform.

We announce new endpoints, behavior changes, and deprecations on the public changelog before they go live.