# Bijify API (v1) **What is Bijify?** Bijify (https://bijify.com) is an AI jewelry-imagery service. You give it a photo of a piece of jewelry and it generates polished product imagery from it: either **On-Body** shots (the jewelry worn by an AI-generated model) or **Still-Life** studio shots, as images or short videos. This document describes the public HTTP API (v1) you call with an API key. It is written to be complete: everything you need to build a full storefront integration is here, including the parts that are easy to get wrong. This is also the canonical generation API we created for bijify.com itself. The web app authenticates with its dashboard session instead of an API key and supplements V1 with private account, history and video-prompt helpers, but upload, discovery, generation and job polling use the same endpoints and response shapes documented here. **Try it / reference implementation:** a browser POC that exercises every endpoint below lives at **https://bijify.com/api-tester/index.html** - paste a valid `ak_...` key into the box and watch the network calls. Its source (`index.html` + `js/app.js`) is the end-to-end example. - **Base URL:** `https://api.bijify.com/api/v1` (always include the path segment after it; a bare `/api/v1` is not routed) - **Auth:** every endpoint requires `Authorization: Bearer ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` (`ak_` + 32 hex chars) - **Format:** JSON in / JSON out, except `POST /upload` (multipart). Send `Content-Type: application/json` on `POST /generate` and `POST /video-generate`. - **CORS:** `Access-Control-Allow-Origin: *` on every response. Preflight answers 204 with `Allow-Methods: GET, POST, OPTIONS`, `Allow-Headers: Content-Type, Authorization`, `Max-Age: 86400`. There are eight endpoints; the quick reference at the end of this document lists them all. Example responses below are real captures (signed-URL tokens shortened). Credit prices and workflow lists are live data - read them at runtime, do not hardcode. **Getting a key.** API access is part of the **Max** plan. On a Max subscription, create your key yourself at **Dashboard -> API Keys** (https://bijify.com/dashboard/api-keys), where you also register its allowed browser domain. One key per account; you can disable, delete and recreate it at any time, and the same screen shows its usage. The key is displayed once at creation - store it somewhere safe. Questions: info@bijify.com. --- ## Authentication Keys have an allowed browser domain. **The domain check runs only when the request carries an `Origin` header.** Cross-origin browser `fetch()` calls to `api.bijify.com` include this browser-controlled header, so JavaScript running on another website cannot pretend to be your registered domain. Server-side HTTP clients and CLIs normally omit `Origin`, and requests without it are accepted without a domain check. When `Origin` is present, matching is exact, `www.`-insensitive, and accepts **any subdomain** of the registered domain: a key for `example.com` accepts `shop.example.com` and `www.example.com`. It is not symmetric - a key registered for `www.example.com` does **not** accept `shop.example.com`. An unknown key, a deactivated key, an expired key, and a domain mismatch are all rejected identically with `401 {"error":"Invalid or expired token"}` on **every** endpoint - authentication runs before dispatch, so the endpoint makes no difference, and the API deliberately does not tell you which of the four it was. A missing or non-`Bearer` header returns `401 {"error":"Authentication required"}` plus a `message` field. `{"error":"Authentication failed"}` only appears for a 401/403 raised *after* auth succeeded - in practice, asking for a job that is not yours. Switch on the status, not the string. Every successful request is logged against the key with your IP, User-Agent and country. **Keep the key on your server.** It is a bearer credential with spend authority. The allowed browser domain prevents direct reuse by JavaScript on another website, but it is not stolen-key protection: a server or CLI can omit `Origin`, or set it to any value. If you embed the key in browser JavaScript, anyone can recover it from the bundle or Network panel and then spend your credits from a server-side client. Route calls through your backend, authenticate your own customers there, and enforce any per-user or per-order limits yourself; Bijify attributes the traffic to your account and has no per-end-user quota. ## Errors Always JSON. **Switch on the status code, never on the message.** `/generate` and `/video-generate` shape-check the body first, and those failures return a real message - e.g. `400 {"error":"storage_key is required (use /upload first)"}`; an unparseable body returns `500 {"error":"Generation failed"}` or `{"error":"Video generation failed"}` respectively. **`/upload` has no such pass**, so every one of its failures - oversized file, bad type, quota - is sanitized. Once a request reaches the generation pipeline, every error out of it (and out of `/jobs/{id}` and `/upload`) is sanitized to one of these fixed strings: | Status | Body | Meaning | |---|---|---| | 400 / 429 / 4xx | `{"error":"Request failed"}` | bad request, quota, or rate limit | | 402 | `{"error":"Request failed"}` | **insufficient credits** | | 401 / 403 | `{"error":"Authentication failed"}` | a job that is not yours (a bad key is rejected earlier, see Authentication) | | 404 | `{"error":"Not found"}` | unknown job, or unknown `workflow_id` | | 5xx | `{"error":"Service temporarily unavailable"}` | server error - *also what an invalid `mode` or a malformed `category_states` produces* | `/modes`, `/schema`, `/workflows` and `/inspiration` are not sanitized and return real messages, e.g. `400 {"error":"Invalid mode: xyz"}`. Infrastructure failures (502/504/52x from the edge) may return **HTML, not JSON**. Always guard your parse. A 500 is not always our fault: an unknown `mode`, a `category_states` value of `null`, or `custom: true` without a `custom_value` string all throw internally and surface as `500 Service temporarily unavailable`. Validate client-side. ## Limits and money **Rate limit.** Uploads and job starts share a single sliding window of **500 requests per rolling hour**, and API-key traffic currently shares that counter globally rather than per-key. Treat the effective budget as well below 500/h and back off on any 429. There is no `Retry-After` header. **Upload limits.** 50 MiB per file (`400` if exceeded) and 1000 MiB of *new* bytes per account per UTC day (`429` if exceeded; the whole upload is rejected rather than partly counted). Deduplicated re-uploads are free and do not count against the daily quota. **Credits.** Each run costs the `credits` figure `/workflows` reports for that workflow. Your balance is **checked** when the job is accepted (`402` if you are short) and **charged only when the job succeeds**. A `failed` job - including one killed by the 90-minute watchdog - is never charged, so a failure costs you nothing but time. Nothing is held between the check and the charge. Two consequences that affect how you design: - **Concurrent submissions are not serialized.** Ten 25-credit jobs fired at once against a 30-credit balance all pass the check and all return `202`. The final charge is capped at your remaining balance, so you cannot go negative, but you also cannot rely on `402` to throttle a burst. Queue your own submissions if that matters. - **Count completions, not acceptances.** There is **no way to read your credit balance with an API key**. If you keep your own ledger, sum `credits` per job you observe `completed`; summing accepted jobs over-counts every failure. A job you stop polling has an outcome you never learn, so any self-kept ledger drifts - treat it as an estimate and read the real balance from the Bijify dashboard. --- ## How a job works 1. **Upload** your image bytes with `POST /upload` -> get a `storage_key` (+ file metadata). 2. **Pick a workflow** from `GET /workflows`. For images also pick a **mode** (`GET /modes`) and **presets** (`GET /schema?mode=...`). Video uses a freeform text `prompt` instead. 3. **Start the job**: `POST /generate` (image) or `POST /video-generate` (video) -> get a job `id`. 4. **Poll** `GET /jobs/{id}` until `status` is `completed` (or `failed`); read the output at `result.output.url` **and download it immediately**. There is no "generate from a URL" shortcut: if your source is a remote URL, download the bytes yourself then `POST /upload`. Doing that fetch from browser JS usually fails - most image hosts send no CORS headers. Fetch server-side. A `storage_key` can be reused in as many `/generate` and `/video-generate` calls as you like, which is how you offer "try 6 styles on one photo" without re-uploading. IDs for modes, categories and presets are opaque 12-hex tokens (e.g. `d66bfe287849`), not readable slugs. Always read them from `/modes` and `/schema`; never hardcode or guess them, and **never key on labels** - labels are display text, they get renamed, and two categories in On-Body Women's share the label "Pose". ### The one exception: finding the Subject category The most common storefront need - open the picker with Subject preset to Ring because the shopper is on a ring product page - needs one id you cannot discover generically. These are stable; you may hardcode them: | Mode | Subject category | Ring | Earrings | Necklace | Bracelet | |---|---|---|---|---|---| | On-Body Women's `d66bfe287849` | `ef7618d5524d` | `981531a8cea2` | `4c8d3f9d5b1a` | `6087c804fac1` | `3df16635e183` | | Still-Life `d3766436ba3f` | `a965ce25e795` | `cee2214426e4` | `ce7420ba83a2` | `83a685efaeb9` | `6eed58edee7d` | These are also the labels the `/inspiration?jewelry=` filter matches on. Everything else should be read at runtime. --- ## Endpoints ### POST /upload Multipart. The file field MUST be named `image`, and the part must declare a content type of `image/jpeg`, `image/jpg`, `image/png` or `image/webp` - a `Blob` built by hand with no type is rejected before the bytes are read. The content is then validated by magic signature (JPEG `FF D8 FF`, the 8-byte PNG signature, or `RIFF`...`WEBP`), so `file_type` in the response is the **detected** type, not what you declared. ``` POST /api/v1/upload Authorization: Bearer ak_... Content-Type: multipart/form-data image = (required) original_sha256 = <64 hex> (optional - see below) source = "bijify" | "video" (optional, default "bijify") ``` Real success (200): ```json { "url": "https://api.bijify.com/api/inference/images/users//content/.jpg?token=...", "storage_key": "users//content/.jpg", "file_name": "bij_input.png", "file_size": 171693, "file_type": "image/jpeg" } ``` Pass `storage_key`, `file_name`, `file_size`, `file_type` into the next step. The `url` is a temporary signed preview (2 h). `file_size` echoes what you sent. **Deduplication.** The storage key is `users//content/.`. Upload the same bytes twice and you get the same `storage_key`, the second upload is discarded, and it does not count against your daily quota. The extension comes from your filename, so identical bytes sent as `.jpg` and as `.png` become two separate objects. **`original_sha256`** overrides the dedup identity with a hash you supply and forces the key extension to `.jpg`. It must be exactly 64 hex chars or it is silently ignored. **It is never verified against the bytes you send.** If the hash collides with one of your own earlier uploads, the server returns that earlier image's `storage_key` and throws away the bytes you just sent - and you will then generate from the wrong picture, with no error anywhere. It exists for clients that compress before uploading. Canvas JPEG output is not byte-stable across browsers, so hashing the compressed bytes would defeat dedup. The recommended pipeline, which is what bijify.com itself does: ``` sha256(original bytes) -> compress to JPEG (longest side <= 2048, quality 0.85, skipped if already JPEG and < 500 KB) -> upload(compressed, original_sha256: ) ``` If you are not compressing client-side, omit `original_sha256` entirely. **`source`** is `"bijify"` (default) or `"video"`; any other value is treated as `"bijify"`. `source=video` triggers an internal image-understanding pass whose result **you cannot retrieve** (described under Video prompts below). Do not send it. ### GET /workflows ```json { "workflows": [ { "id": "bijify-image-lite", "name": "Bijify Image", "description": null, "category": "image", "credits": 25, "health": { "status": "green", "score": 100, "avgGenerationSeconds": 12.95 } }, { "id": "bijify-video-pro", "name": "Bijify Video", "description": null, "category": "video", "credits": 300, "health": { "status": "green", "score": 100, "avgGenerationSeconds": 142.86 } } ] } ``` Six workflows are returned today. The `name` field distinguishes them, but nothing in the API tells you the resolution or speed you are buying, so here is what each one actually is - this is what bijify.com shows its own users: | id | What it is | Resolution | Typical | |---|---|---|---| | `bijify-image-lite` | Standard definition, fast | 1K | ~13 s | | `bijify-image-pro` | High quality and definition, slower | 2K | ~44 s | | `bijify-image-pro-2` | Higher quality and definition | 2K | ~31 s | | `bijify-video-pro` | Current video model | 1080p | ~143 s | | `bijify-video-legacy-lite` / `-legacy-pro` | Previous-generation video, kept for continuity | - | - | The Pro image workflows deliberately drop the enhancement controls they make redundant (Size, Skin Realism, Beauty and Quality on On-Body Women's; Size and Quality on Still-Life) via the `__workflow__` rule - though those categories are internal, so you never see them in `/schema` anyway. Prefer the current `bijify-video-pro` over the legacy video workflows for new work. - `category` decides `/generate` vs `/video-generate`. - `credits` is the cost per run. Read it at runtime. - `description` may be `null`; do not depend on it. - `health` is always present, but **`health.avgGenerationSeconds` is omitted until the workflow has recent runs** - defend against that, since it is what you size your polling deadline from. `score` is the recent success rate out of 100 and `status` has **four** values: `green` (>=90), `yellow` (75-89), `orange` (50-74), `red` (<50). Treat `orange` and `red` as degraded. A workflow with no history reports `green`/`100` - that is a cold-start default, not evidence. - `name` is a stable server-side display name, unlike mode and preset labels. `workflow_id` is not validated against this list. Any workflow id that exists server-side is reachable; an unknown one returns 404. ### GET /modes Trimmed sample (2 of the 6 returned): ```json { "modes": [ { "id": "d66bfe287849", "label": "On-Body Women's Jewelry", "restricted": false }, { "id": "d3766436ba3f", "label": "Still-Life Jewelry", "restricted": false } ] } ``` Every object has `id`, `label` and `restricted`. **API keys see every mode** - currently six, four flagged `restricted: true`. Those four are hidden from the Bijify web dashboard because they are work in progress; they answer `/schema` and `/generate` normally for you, but they may change or disappear without notice. Build against `restricted: false` modes unless you have agreed otherwise with us. ### GET /schema?mode={modeId} Categories and presets for a mode. On-Body Women's returns **23 of its 30** categories (7 are internal); Still-Life returns **27 of 31** (4 internal). Trimmed sample: ```json { "mode": "d66bfe287849", "mode_label": "On-Body Women's Jewelry", "categories": [ { "id": "ef7618d5524d", "label": "Subject", "presets": [ { "id": "981531a8cea2", "label": "Ring" }, { "id": "4c8d3f9d5b1a", "label": "Earrings" }, { "id": "6087c804fac1", "label": "Necklace" }, { "id": "3df16635e183", "label": "Bracelet" } ] }, { "id": "0d3684b8d739", "label": "Camera", "presets": [ { "id": "a54085214de1", "label": "Close-Up" }, { "id": "2ace0d27529f", "label": "Portrait" } ] }, { "id": "7f49cbdd9af5", "label": "Age", "default": "e8a51c25f2da", "presets": [ { "id": "187e76db8609", "label": "Young" }, { "id": "e8a51c25f2da", "label": "Young Adult" } ] } ], "rules": [ ... ] } ``` - Pick a category's initial value as `category.default ?? category.presets[0].id`. That is exactly what bijify.com does. `default` is present on only some categories and is a **hint for you** - the server never applies it to a category you omit. - Internal (`visible:false`) categories are not returned here, but they are real: the server auto-fills them, and they do appear inside `_ui_state` template payloads. Pass such ids through unchanged rather than filtering them out. - Missing `mode` -> `400 {"error":"Missing mode parameter"}`. Unknown mode -> `400 {"error":"Invalid mode: "}`. - `rules` has its own section below. **Read it** - it is what makes the picker behave. ### POST /generate (image) ```json { "workflow_id": "bijify-image-lite", "storage_key": "users//content/.jpg", "file_name": "bij_input.png", "file_size": 171693, "file_type": "image/jpeg", "aspect_ratio": "1:1", "mode": "d66bfe287849", "category_states": { "ef7618d5524d": { "selected_preset": "981531a8cea2", "custom": false, "custom_value": "" }, "0d3684b8d739": { "selected_preset": "a54085214de1", "custom": false, "custom_value": "" }, "7f49cbdd9af5": { "selected_preset": "e8a51c25f2da", "custom": false, "custom_value": "" } } } ``` Send all of `workflow_id`, `storage_key`, `file_name`, `file_size` (a number), `file_type`, `mode` and `category_states`. The v1 shape check returns 400 only when one of the first five is absent. Missing `mode` returns 500 as described below. Missing or empty `category_states` is unfortunately accepted: the job runs using only the mode's hidden defaults, and a successful result is charged normally. Treat both fields as required in your client. `aspect_ratio` is optional, default `"1:1"`. Omitting `mode`, or sending one that is not a real mode id, both return **`500`** - the v1 layer substitutes a placeholder for a missing `mode` and the generator then rejects it. There is no 400 for either case, so validate mode ids client-side against `/modes`. `storage_key` is neither ownership-checked nor existence-checked. A typo returns `202 accepted`, runs, and fails minutes later with the generic `"Generation failed"`. You are not charged for it, but you have burned the round trip. Response (HTTP 202) - the job object, same shape as `/jobs/{id}`: ```json { "id": "d643477d-1205-4f54-930a-e82276f58d12", "status": "accepted", "progress": 0, "result": null, "error": null, "createdAt": "2026-06-15T13:13:57.202Z", "updatedAt": "2026-06-15T13:13:57.202Z" } ``` #### category_states format Each value is an object with **all three fields present**: ```json "": { "selected_preset": "", "custom": false, "custom_value": "" } ``` - Normal case: a preset id from `/schema`, `custom: false`, `custom_value: ""`. - Free-text override: `custom: true` with your text in `custom_value`. The text **replaces** that category's preset wording in the prompt - you lose the preset's built-in phrasing rather than adding to it. - **`selected_preset` is still what the rules evaluate against, even when `custom` is true.** Setting `custom: true` with an empty `selected_preset` silently flips rule outcomes and excludes the wrong categories. Always keep a valid preset id alongside your custom text. - **Send a state for every category `/schema` returns.** A visible category you omit is not defaulted - it contributes nothing to the prompt, *and* its absence changes rule evaluation (a rule leaf on a missing category is always false). - A bare string (`"": ""`) does not work: the server reads `.selected_preset`, gets `undefined`, and silently drops the category. No error. - A `selected_preset` is not checked against that category's current preset list. An unknown or stale id becomes literal prompt text; the job still runs and a success is charged. Before replaying saved state, re-read `/schema` and re-seed each stale visible category to `category.default ?? category.presets[0].id`; neither omit the category nor leave its preset empty, because both change rule evaluation. Templates supplied by `/inspiration` may include internal category ids absent from `/schema`; preserve those unchanged. - `null`, or `custom: true` without a `custom_value` string, throws and returns **500**. - This is the exact shape stored inside inspiration templates. ### POST /video-generate (video) Uses a freeform `prompt` instead of mode/presets. ```json { "workflow_id": "bijify-video-pro", "storage_key": "users//content/.jpg", "file_name": "photo.jpg", "file_size": 171693, "file_type": "image/jpeg", "prompt": "slow cinematic orbit around the ring, soft studio light", "duration": 5 } ``` Required: `workflow_id`, `prompt` (non-empty after trimming), `storage_key`, `file_name`, `file_size`, `file_type`. Optional: `duration`, default `5`. **`duration` must be `5` or `10`.** Other values are not rejected at request time - the job is accepted and comes back `failed` (uncharged). Duration does not change the credit cost. **Do not rely on `aspect_ratio` here.** It defaults to `"1:1"` server-side whether you send it or not. On the primary path, `bijify-video-pro` ignores it and follows your input image; the legacy Seedance workflows and the failover provider do honor it. So the same request can produce different framing depending on which backend served it. **Crop your input image to the shape you want the video to be**, and if you do send the field, send a value the model accepts (`16:9`, `9:16` or `1:1` for `bijify-video-pro`). Response is the same job object. ### GET /jobs/{id} ```json { "id": "d643477d-1205-4f54-930a-e82276f58d12", "status": "completed", "progress": 100, "result": { "output": { "url": "https://api.bijify.com/api/inference/images/users//outputs//1781529248029-7.jpg?token=...", "key": "users//outputs//1781529248029-7.jpg", "bucket": "output", "type": "image" }, "outputName": "output" }, "error": null, "createdAt": "2026-06-15T13:13:57.202Z", "updatedAt": "2026-06-15T13:14:09.165Z" } ``` The response never contains any field beyond these seven. - `status` is exactly one of `accepted`, `processing`, `completed`, `failed`. Jobs cannot be cancelled. - `progress` is 0-100, allocated across the pipeline's internal steps. It moves in coarse jumps and is **not** a time estimate - drive your ETA from `avgGenerationSeconds` instead. - `result.output.type` is `"image"` or `"video"` - **use it to decide whether to render an `` or a `