{
  "info": {
    "_postman_id": "8f7c1d3e-2b64-4a1e-9c58-photosweat0001",
    "name": "PhotoSweat · Background Removal API",
    "description": "Photosweat (https://photosweat.shop) — a runnable collection for the background-removal API.\n\n**Three steps to a cutout**\n1. Import this file and `photosweat.postman_environment.json`.\n2. In the environment, fill `apiKey` if you have one; leave it empty to use the anonymous allowance. `baseUrl` already points at production.\n3. Run the first request in \"01 Quick start\"; the \"02\" folder walks the presign → PUT → create job → poll → fetch flow.\n\nThe collection-level pre-request script adds `Authorization: Bearer …` only when `apiKey` is non-empty, so the whole collection runs without a key.\n\nFree tiers: 10 images/day per anonymous IP, 30/day with a key. Beyond that $0.01 per image ($10 = 1,000 prepaid images, never expiring). Failed jobs are refunded.\n\nEvery path and field is defined by https://photosweat.shop/openapi.json. Only one tool is live today (`remove_background`); the other capabilities in `/api/tools` are paused and return 404 without consuming quota.\n\n中文说明：导入后跑「01 Quick start」的第一条请求即可出图；不填 `apiKey` 走匿名额度。",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "jobId",
      "value": ""
    },
    {
      "key": "uploadUrl",
      "value": ""
    },
    {
      "key": "resultUrl",
      "value": ""
    },
    {
      "key": "pollCount",
      "value": "0"
    }
  ],
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Only send Authorization when a key is set; otherwise run on the anonymous per-IP allowance.",
          "const k = (pm.variables.get('apiKey') || '').trim();",
          "if (k) {",
          "  pm.request.headers.upsert({ key: 'Authorization', value: 'Bearer ' + k });",
          "}"
        ]
      }
    }
  ],
  "item": [
    {
      "name": "01 Quick start — one image",
      "item": [
        {
          "name": "Remove background (send bytes, get JSON)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "if (res.result_url) pm.collectionVariables.set('resultUrl', res.result_url);",
                  "if (res.job_id) pm.collectionVariables.set('jobId', res.job_id);",
                  "pm.test('200 with the image, or 202 queued', () => pm.expect([200, 202]).to.include(pm.response.code));",
                  "pm.test('Response carries job_id', () => pm.expect(res.job_id).to.be.a('string'));",
                  "if (res.status === 'done') {",
                  "  pm.test('result_url present when done', () => pm.expect(res.result_url).to.be.a('string'));",
                  "} else {",
                  "  pm.test('status_url present when queued', () => pm.expect(res.status_url).to.be.a('string'));",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "image/png"
              },
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{$guid}}",
                "description": "Resending with the same key uses no extra quota and creates no second job"
              }
            ],
            "body": {
              "mode": "file",
              "file": {
                "src": ""
              }
            },
            "url": {
              "raw": "{{baseUrl}}/api/remove-background?params=%7B%22background%22%3A%22transparent%22%7D",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "remove-background"
              ],
              "query": [
                {
                  "key": "params",
                  "value": "{\"background\":\"transparent\"}"
                }
              ]
            },
            "description": "Choose **Binary** as the body and pick a local PNG (or switch Content-Type to `image/jpeg` / `image/webp`).\n\n`params` is a JSON string in the query string: `background` is `transparent` / `white` / `color`; `format` is `png` / `jpeg` / `webp`.\n\nThe Worker waits at the edge: a result within 20 s comes back as `200` (JSON carrying `result_url`); otherwise `202` with `status_url` — the image is not lost."
          }
        },
        {
          "name": "Fetch the resulting image (Send and Download)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{resultUrl}}",
              "host": [
                "{{resultUrl}}"
              ]
            },
            "description": "Use Send and Download to save it. `result_url` is a signed URL valid for one hour; after that, create a new job or call `/api/jobs/{id}` for a fresh one."
          }
        }
      ]
    },
    {
      "name": "02 Presign → upload → poll → fetch",
      "item": [
        {
          "name": "① Request an upload URL (uses 1 image of quota)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "pm.test('200 returns jobId and uploadUrl', () => {",
                  "  pm.expect(pm.response.code).to.eql(200);",
                  "  pm.expect(res.jobId).to.be.a('string');",
                  "  pm.expect(res.uploadUrl).to.be.a('string');",
                  "});",
                  "pm.collectionVariables.set('jobId', res.jobId);",
                  "pm.collectionVariables.set('uploadUrl', res.uploadUrl);",
                  "pm.collectionVariables.set('pollCount', '0');"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"size\": {{imageSize}},\n  \"type\": \"image/png\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/presign",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "presign"
              ]
            },
            "description": "Quota is deducted **here**, not when the job is created, so requesting repeatedly burns quota.\n\n`size` is declared from the environment's `imageSize` (bytes, max 10485760); the real size is checked against the object-storage HEAD when the job is created."
          }
        },
        {
          "name": "② PUT the bytes to uploadUrl",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test('Upload succeeded (object storage returns 200)', () => pm.expect(pm.response.code).to.be.oneOf([200, 201]));"
                ]
              }
            }
          ],
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "image/png"
              }
            ],
            "body": {
              "mode": "file",
              "file": {
                "src": ""
              }
            },
            "url": {
              "raw": "{{uploadUrl}}",
              "host": [
                "{{uploadUrl}}"
              ]
            },
            "description": "Pick the same file as the binary body. This goes straight to object storage (R2 S3 endpoint), not through the Worker.\n\nContent-Type must match the `type` declared in ①, or the job is rejected as `unsupported_media_type`."
          }
        },
        {
          "name": "③ Create the job",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "pm.test('202 (or 200 if it already finished synchronously)', () => pm.expect([200, 202]).to.include(pm.response.code));",
                  "pm.test('status is queued / processing / done', () => pm.expect(['queued', 'processing', 'done']).to.include(res.status));"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"jobId\": \"{{jobId}}\",\n  \"capability\": \"image.cutout\",\n  \"params\": { \"background\": \"transparent\" }\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/jobs",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "jobs"
              ]
            },
            "description": "`capability` takes an id from `/api/tools`; `image.cutout` is background removal (transparent), `image.white-bg` is a white-background product shot.\n\n`params` can be omitted entirely; omitted fields fall back to defaults."
          }
        },
        {
          "name": "④ Poll until done (retries automatically)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "const n = Number(pm.collectionVariables.get('pollCount') || 0) + 1;",
                  "pm.collectionVariables.set('pollCount', String(n));",
                  "pm.test('status is readable', () => pm.expect(res.status).to.be.a('string'));",
                  "if (res.status === 'done') {",
                  "  pm.collectionVariables.set('pollCount', '0');",
                  "  const url = res.resultUrl || res.downloadUrl || '';",
                  "  if (url) pm.collectionVariables.set('resultUrl', url);",
                  "  pm.test('got the result URL when done', () => pm.expect(url).to.not.eql(''));",
                  "} else if (res.status === 'error' || res.status === 'expired') {",
                  "  pm.collectionVariables.set('pollCount', '0');",
                  "  pm.test('job failed (quota refunded)', () => pm.expect.fail('job ended ' + res.status + ': ' + (res.error || '')));",
                  "} else if (n < 60) {",
                  "  postman.setNextRequest('④ Poll until done (retries automatically)');",
                  "} else {",
                  "  pm.collectionVariables.set('pollCount', '0');",
                  "  pm.test('still not done after 60 polls', () => pm.expect.fail('still ' + res.status + ' — run it in Runner or click again later'));",
                  "}",
                  "pm.test('202 or 200, both fine', () => pm.expect([200, 202]).to.include(pm.response.code));"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/jobs/{{jobId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "jobs",
                "{{jobId}}"
              ]
            },
            "description": "The read endpoint is not rate-limited and retries up to `done` (60 times). To go gentler, set a 2000 ms delay in Collection Runner.\n\nOn `done`, `resultUrl` is stored in a variable — run \"Fetch the resulting image\" next."
          }
        }
      ]
    },
    {
      "name": "03 Batch + callbacks",
      "item": [
        {
          "name": "Two images in one batch (optional callback)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "pm.test('202 created a batch', () => {",
                  "  pm.expect(pm.response.code).to.eql(202);",
                  "  pm.expect(res.count).to.eql(2);",
                  "  pm.expect(res.jobs).to.be.an('array').with.lengthOf(2);",
                  "});",
                  "if (res.jobs && res.jobs[0]) pm.collectionVariables.set('jobId', res.jobs[0].job_id);"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Idempotency-Key",
                "value": "postman-batch-{{$timestamp}}"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "image",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "image",
                  "type": "file",
                  "src": ""
                },
                {
                  "key": "params",
                  "type": "text",
                  "value": "{\"background\":\"white\"}"
                },
                {
                  "key": "callback_url",
                  "type": "text",
                  "value": "{{callbackUrl}}",
                  "disabled": true,
                  "description": "https only; leave disabled if you do not need it"
                },
                {
                  "key": "callback_secret",
                  "type": "text",
                  "value": "{{callbackSecret}}",
                  "disabled": true
                }
              ]
            },
            "url": {
              "raw": "{{baseUrl}}/api/batch",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "batch"
              ]
            },
            "description": "1–10 images sharing one set of `params`. Billing is atomic per batch: if one image cannot be charged, no job in the batch is created and anything already charged is refunded.\n\nWith `callback_url` set you do not poll: we POST once per image when it reaches a terminal state, carrying `x-photosweat-signature: t=…,v1=…` when a secret is configured, backing off 30s/2m/10m/1h/6h, at most 6 attempts. The payload is metadata only — no image bytes."
          }
        },
        {
          "name": "Fetch the first image in the batch",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/jobs/{{jobId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "jobs",
                "{{jobId}}"
              ]
            },
            "description": "`jobs[i].status_url` returned by the batch call is this same endpoint."
          }
        }
      ]
    },
    {
      "name": "04 Quota and account",
      "item": [
        {
          "name": "Today's quota and balance",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/me",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "me"
              ]
            },
            "description": "With a key, reports that key; without one, reports this IP's anonymous quota. `credits` is the prepaid balance in images."
          }
        },
        {
          "name": "Tool catalogue",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/tools",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "tools"
              ]
            },
            "description": "Every capability with its parameters, whether it is live, and its price."
          }
        },
        {
          "name": "Service health",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/status",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "status"
              ]
            },
            "description": "Healthy `200` / degraded `503`. Point your own probe at it."
          }
        },
        {
          "name": "Send a sign-up email code",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{email}}\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/auth/email/start",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "auth",
                "email",
                "start"
              ]
            },
            "description": ""
          }
        },
        {
          "name": "Sign up (6-digit code from the email)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const res = pm.response.json();",
                  "if (res.key) pm.collectionVariables.set('apiKey', res.key);",
                  "pm.test('got the key', () => pm.expect(res.key || res.apiKey || '').to.not.eql(''));"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{email}}\",\n  \"password\": \"{{password}}\",\n  \"code\": \"{{emailCode}}\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/auth/signup",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "auth",
                "signup"
              ]
            },
            "description": "On success the key is written to the `apiKey` variable, and every later request sends it automatically."
          }
        },
        {
          "name": "Buy a pack of 1,000 images ($10)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/auth/credits/buy",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "auth",
                "credits",
                "buy"
              ]
            },
            "description": "Needs a signed-in session (browser) or a key; returns the Stripe checkout URL."
          }
        }
      ]
    }
  ]
}
