Build with GENCY lite

Get from zero to your first API call in three steps.

1. 1Open Settings → API Keys in your GENCY lite workspace (owner only) and create a key. The plaintext key is shown only once — copy it somewhere safe.
2. 2Export it in your shell: export KEY=glk_live_...
3. 3Call the API to confirm your key and plan:

bashcurl https://lite.gency.ai/api/v1/me \
  -H "Authorization: Bearer $KEY"

A successful response returns your workspace, plan, and credit balance:

json{
  "orgId": "…",
  "plan": "growth",
  "planStatus": "active",
  "credits": { "used": 1200, "limit": 21000, "remaining": 19800, "unlimited": false }
}

Every request is authenticated with a Bearer token. Keys are created under Settings → API Keys (workspace owner only) and only a hash is stored — if a key leaks, revoke it and issue a new one.

Authorization: Bearer glk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The same key works for both the REST API (/api/v1) and the MCP server (/api/mcp).

Calls deduct workspace credits exactly like the UI (billed to the owner's subscription). Credits are automatically refunded if processing fails.

Errors use a consistent JSON shape:

json{ "error": "description", "code": "insufficient_credits", "required": 100, "available": 40 }

Idempotency. Send an Idempotency-Key header (any unique string) on POST requests to retry safely — a completed request replays its stored response without charging credits again. Same key with a different body returns 422; a still-processing one returns 409. Keys are remembered for 24 hours.

Base URL https://lite.gency.ai/api/v1. Images accept a public https:// URL or base64 (max 20 MB).

bashcurl -X POST https://lite.gency.ai/api/v1/uploads \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"image":"data:image/png;base64,iVBOR..."}'

bashcurl -X POST https://lite.gency.ai/api/v1/images/remove-background \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/shoe.jpg"}'

bashcurl -X POST https://lite.gency.ai/api/v1/images/edit \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "place the product on a marble kitchen counter, soft daylight",
    "images": ["https://example.com/cutout.png"],
    "aspectRatio": "1:1"
  }'

bashcurl -X POST https://lite.gency.ai/api/v1/aplus/generate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "images": ["https://…/1.jpg", "https://…/2.jpg"],
    "categoryId": "fashion",
    "lang": "en"
  }'

bashcurl -X POST https://lite.gency.ai/api/v1/listing/generate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<uuid from /aplus/generate>","lang":"en"}'

bashcurl -X POST https://lite.gency.ai/api/v1/aplus/translate \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<uuid from /aplus/generate>","lang":"ja"}'

A remote MCP (Model Context Protocol) server lets AI agents such as Claude call GENCY lite tools directly. Endpoint https://lite.gency.ai/api/mcp — stateless Streamable HTTP, JSON-RPC 2.0, same API key.

Auth: a static API key (glk_live_…), not OAuth — attach it as an Authorization: Bearer header. Once connected, the agent auto-discovers the tools; nothing else to configure.

Claude Code

bashclaude mcp add --transport http gency-lite https://lite.gency.ai/api/mcp \
  --header "Authorization: Bearer $GENCY_API_KEY"

Codex CLI — ~/.codex/config.toml (bridge via mcp-remote):

toml[mcp_servers.gency-lite]
command = "npx"
args = ["-y", "mcp-remote", "https://lite.gency.ai/api/mcp", "--header", "Authorization: Bearer ${GENCY_API_KEY}"]

Claude Desktop · Cursor · Windsurf · any mcpServers client

json{
  "mcpServers": {
    "gency-lite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://lite.gency.ai/api/mcp",
               "--header", "Authorization: Bearer ${GENCY_API_KEY}"]
    }
  }
}

Call gency_list_capabilities first (free) to learn valid categoryId values, aspect ratios, and limits — it avoids guessing and hitting 400s. Results also include a machine-readable structuredContent object (e.g. { url, credits }) alongside the text, so you don't have to parse URLs out of prose.

Ready-made workflow prompts are exposed via prompts/list: stage_product (cut out + place in a scene) and make_aplus (full A+ page).

Land photos from a capture device directly into a walk-in user's "My Files" in real time. The device never holds user credentials — the user logs in and consents ("Connect") from their own phone via a QR code.

We host the QR and status screen for you. The device only needs to:

1. 1POST /api/v1/device/sessions → open the returned displayUrl in the device's browser (we render the QR, "Connected", "Capturing N photos", "Done").
2. 2Poll the session until status is active, then upload each photo.
3. 3Call POST /sessions/:id/end when finished.

jsconst BASE = "https://lite.gency.ai/api/v1/device";
const h = { Authorization: `Bearer ${DEVICE_KEY}`, "Content-Type": "application/json" };
const s = await (await fetch(`${BASE}/sessions`, {
  method: "POST", headers: h, body: JSON.stringify({ label: "Booth 1" })
})).json();
showQR(s.pairUrl);                       // or open s.displayUrl on the device screen

// poll until the user connects
let st;
do { await sleep(2500);
     st = await (await fetch(`${BASE}/sessions/${s.sessionId}`, { headers: h })).json();
} while (st.status === "pending");
if (st.status !== "active") return;      // expired, etc.

for (const photo of takePhotos()) {
  await fetch(`${BASE}/sessions/${s.sessionId}/photos`, {
    method: "POST", headers: h, body: JSON.stringify({ image: photo.base64 })
  });
}
await fetch(`${BASE}/sessions/${s.sessionId}/end`, { method: "POST", headers: h });