Use My Own Inventory Docs

Base URL

https://zukme.com

Every endpoint below is relative to this base URL. For example, POST /api/v1/inventory/tryon meansPOST https://zukme.com/api/v1/inventory/tryon.

Authentication

Every request must include your API key as a bearer token. Create and manage keys in the API Dashboard. The raw key is shown once at creation; only its hash is ever stored, so if it's lost you must revoke it and create a new one.

Authorization: Bearer zk_live_<your key>

A missing, malformed, or revoked key returns 401:

{ "error": "Invalid or missing API key. Pass it as \"Authorization: Bearer zk_live_...\"." }

Rate limits

Each API key is limited to 30 requests per minute (submit and poll requests both count). Exceeding it returns 429:

{ "error": "Rate limit exceeded.", "retryAfterSeconds": 12 }

Credits

API usage draws from the exact same credit balance as the ZukMe app — the same balance the Pull from Marketplace product shares too — with no separate metering system. Syncing your inventory never costs a credit. Each successful Runway Edit, StyleMe, or Inventory Try-On submission costs 1 credit, deducted when the job is submitted. If generation fails, the credit is refunded automatically. Polling for a job's status never costs a credit. See pricing for subscription tiers, or your account's balance any time via the API Dashboard.

Errors

Example 402 body:

{
  "error": "CREDITS_EXHAUSTED",
  "code": "CREDITS_EXHAUSTED",
  "looks": 0,
  "bonus": 0,
  "total": 0
}

Runway Edit

Generates a photorealistic fashion editorial image: a model wearing an outfit built from your source art/photo, in a scene and style you direct. Runs as an async job: submit, then poll until it's done (generation typically takes 30 to 90 seconds across its internal stages).

POST /api/v1/runway-edit · Submit

Response (submitted):

{ "ok": true, "jobId": "b3f1...", "status": "processing" }

POST /api/v1/runway-edit · Poll

Response while processing:

{ "status": "processing", "stage": "t2i" }

Response when done:

{ "ok": true, "status": "done", "imageUrl": "https://..." }

Response on failure (credit already refunded):

{ "status": "error", "error": "The AI model failed on this image. Please try again." }

StyleMe

Generates a personalized style reading from a photo: a stylist-grade read on colouring, proportions, and aesthetic. Feeds directly into Inventory Try-On below. Also an async job: submit, then poll until done.

POST /api/v1/styleme · Submit

Response (submitted):

{ "ok": true, "jobId": "a91c...", "status": "processing" }

POST /api/v1/styleme · Poll

Same poll shape as Runway Edit. Response when done:

{ "ok": true, "status": "done", "reading": { /* StyleMeReading, see below */ } }

The reading object

Inventory Sync

Push your product catalog here before calling Inventory Try-On below. A full replace — whatever you send becomes your entire matchable catalog. No credits are spent syncing.

PUT /api/v1/inventory/products

The InventoryProduct object

Response:

{ "ok": true, "count": 128 }

GET /api/v1/inventory/products

Returns whatever is currently synced, to confirm a push landed correctly:

{ "ok": true, "products": [ { "id": "sku-001", "name": "Tailored Wool Blazer", ... } ] }

Inventory Try-On

Takes a StyleMe reading and a photo, matches the best piece per garment category from your synced inventory, and renders the result onto the photo. Async job: submit, then poll.

POST /api/v1/inventory/tryon · Submit

Response (submitted):

{ "ok": true, "jobId": "d81f...", "status": "processing" }

POST /api/v1/inventory/tryon · Poll

Same poll shape as Runway Edit. Response when done:

{
  "ok": true,
  "status": "done",
  "imageUrl": "https://...",
  "outfitBreakdown": [
    {
      "category": "top",
      "productId": "sku-001",
      "productName": "Tailored Wool Blazer",
      "imageUrl": "https://...",
      "price": "USD 220",
      "source": "inventory"
    }
  ]
}

If a category has no good match in your current inventory, it's simply omitted from the look rather than invented — sync more products in that category and try again.

Callbacks (webhooks)

runway-edit and inventory/tryon both accept an optional callbackUrl in the submit request. When set, wePOST the same payload a completed poll would return to that URL once the job finishes — success or failure — in addition to, never instead of, polling. Delivery is best-effort: we don't retry or track failed deliveries, so keep polling as your source of truth.

// what we POST to callbackUrl on success:
{ "jobId": "...", "status": "done", "imageUrl": "https://...", "outfitBreakdown": [...] }

// on failure:
{ "jobId": "...", "status": "error", "error": "..." }

callbackUrl must be a public http(s) URL — localhost and private network addresses are rejected.

Job polling

Every submit endpoint returns a jobId and runs asynchronously, since generation involves multiple internal AI stages that don't fit in one request/response cycle. Poll the same endpoint every 2 to 3 seconds until you getstatus: "done" orstatus: "error". A job that returns404 either never existed or has expired. Treat it as failed.

Full example: curl

# 1. Sync your inventory — see Inventory Sync above
# 2. Get a StyleMe reading — see the StyleMe section above
# 3. Submit
curl https://zukme.com/api/v1/inventory/tryon \
  -X POST \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reading": { /* from POST /api/v1/styleme */ },
    "photoBase64": "<base64>",
    "occasion": "Client presentation"
  }'
# → { "ok": true, "jobId": "d81f...", "status": "processing" }

# 4. Poll until done
curl https://zukme.com/api/v1/inventory/tryon \
  -X POST \
  -H "Authorization: Bearer zk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "action": "poll", "jobId": "d81f..." }'
# → { "status": "processing", "stage": "edit" }   (repeat)
# → { "ok": true, "status": "done", "imageUrl": "https://...", "outfitBreakdown": [...] }

Full example: Node.js

const KEY = process.env.ZUKME_API_KEY;
const BASE = "https://zukme.com/api/v1/inventory/tryon";

async function call(body) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  return res.json();
}

const submitted = await call({
  reading, // from POST /api/v1/styleme
  photoBase64,
  occasion: "Client presentation",
});

let result;
while (true) {
  result = await call({ action: "poll", jobId: submitted.jobId });
  if (result.status === "done" || result.status === "error") break;
  await new Promise((r) => setTimeout(r, 2500));
}

console.log(result); // { ok: true, status: "done", imageUrl: "...", outfitBreakdown: [...] }

Full example: Python

import os, time, requests

KEY = os.environ["ZUKME_API_KEY"]
BASE = "https://zukme.com/api/v1/inventory/tryon"
headers = {"Authorization": f"Bearer {KEY}"}

submitted = requests.post(BASE, headers=headers, json={
    "reading": reading,  # from POST /api/v1/styleme
    "photoBase64": photo_base64,
    "occasion": "Client presentation",
}).json()

while True:
    result = requests.post(BASE, headers=headers, json={
        "action": "poll", "jobId": submitted["jobId"],
    }).json()
    if result["status"] in ("done", "error"):
        break
    time.sleep(2.5)

print(result)  # {'ok': True, 'status': 'done', 'imageUrl': '...', 'outfitBreakdown': [...]}