{"openapi":"3.1.0","info":{"title":"PhotoSweat API","version":"1.0.0","summary":"Image restoration, colorization, background removal and upscaling.","description":"**One tool is live right now: `POST /api/remove-background`** ($0.01/image USD).\nSend the image bytes (raw or multipart) and get the image back — transparent, white, or any solid color.\nAnonymous calls work with no key: 10 images/day per IP. A free key raises that to 30/day.\nPast the daily allowance, prepaid credits are spent automatically: $10 buys 1000 images (account page),\ndeducted one per image, never expiring. `GET /v1/me` reports the balance as `credits`; responses that\nspent a credit carry `x-credits-left`.\n\nThe other capabilities (enhance, colorize, erase, upscale, extend, scan-text, generate) are registered\nbut paused — they return `404 tool_paused` and cost nothing. Do not rely on them. `GET /api/tools` is\nthe runtime catalog (slug, status, price, params); `https://photosweat.shop/llms.txt` is the human/agent guide.\n\n`wait` = how many seconds the request blocks (1–25, default 20). If the job is still running you get\n`202` with `job_id` and `status_url`; the job is not lost. `format=json` returns JSON with a signed\n`result_url` instead of the image bytes. Results live for 24 hours.\n\nThe browser app uses the three-step flow (`/api/presign` + PUT + `/api/jobs`); `POST /v1/run` was retired\non 2026-11-18 and now returns 404 — use `POST /api/remove-background` instead.","license":{"name":"Proprietary"}},"servers":[{"url":"https://photosweat.shop"}],"paths":{"/v1/me":{"get":{"operationId":"getQuota","summary":"Today's quota usage — for this key, or for the calling IP when no key is sent","description":"Works anonymously too: without an `Authorization` header it reports the IP's anonymous ledger. A bad key never falls back to anonymous — it returns 401.","security":[{},{"bearerKey":[]}],"responses":{"200":{"description":"Quota (`kind`, `limit`, `used`, `remaining`, `credits`, `rate_limit_per_min`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quota"}}}},"401":{"description":"Invalid/revoked key, or anonymous access closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/keys":{"post":{"operationId":"issueAccountKey","summary":"Issue another key for the signed-in account (needs the pt_sess session cookie)","description":"Keys belong to accounts, so this needs a session — sign in on the website first. At most 3 active keys per account; issuing a 4th revokes the oldest. `POST /api/auth/keys` is the same handler.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":40,"description":"Optional label"}}}}}},"responses":{"200":{"description":"Key issued — the plaintext is returned exactly once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"401":{"description":"Not signed in, or the session expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/email/start":{"post":{"operationId":"startEmailCode","summary":"Send a 6-digit verification code to an email address","description":"Step 1 of registration. The code proves the address belongs to the caller and is valid for\n5 minutes. Per-address limit: 10 sends/hour. Returns 501 when the deployment has no mail\nchannel configured (then password signup takes no code).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Code sent (or already sent recently — the response says which)"},"400":{"description":"Not a valid email address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many codes for this address this hour","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"No mail channel on this deployment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/signup":{"post":{"operationId":"signup","summary":"Create an account with email + password and get a free API key","description":"Returns the plaintext key (`sk_free_…`) exactly once and sets the `pt_sess` session cookie.\nOn deployments with a mail channel the request must also carry the 6-digit `code` from\n`POST /api/auth/email/start`; without it the body is `400 code_required`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"code":{"type":"string","pattern":"^[0-9]{6}$","description":"Email verification code"}}}}}},"responses":{"200":{"description":"Account created — the plaintext key is in the body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"400":{"description":"Bad email/password, or `code_required` when the deployment needs a code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`bad_code` — wrong or expired verification code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/login":{"post":{"operationId":"login","summary":"Sign in with email + password; sets the pt_sess session cookie","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Signed in"},"401":{"description":"Wrong email or password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/email/verify":{"post":{"operationId":"verifyEmailCode","summary":"Sign in with only an email code — creates the account on first use","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"}}}}}},"responses":{"200":{"description":"Signed in (and registered if new) — key in the body for new accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKey"}}}},"401":{"description":"`bad_code` — wrong or expired code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/me":{"get":{"operationId":"whoami","summary":"The signed-in account: email, plan, keys, today's usage and prepaid credit balance","security":[{"bearerKey":[]}],"responses":{"200":{"description":"Account, keys, usage and `credits.balance`"},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/credits/buy":{"post":{"operationId":"buyCredits","summary":"Start a Stripe Checkout for one pack of prepaid images ($10 = 1000 images)","description":"Returns a Stripe Checkout URL. Credits are added only when Stripe's signed webhook confirms the payment — `success_url` alone grants nothing. Requires an account session; anonymous callers get 401. Without `STRIPE_SECRET_KEY` configured the endpoint answers 501 `configured: false`.","responses":{"200":{"description":"`{ url, id, credits, priceUsd }` — redirect the browser to `url`"},"401":{"description":"`not_logged_in`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Payments not configured (`configured: false`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Stripe unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/capabilities":{"get":{"operationId":"listCapabilities","summary":"List capabilities and their parameters","responses":{"200":{"description":"Capability list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}}}}},"/api/tools":{"get":{"operationId":"listTools","summary":"List the public tools: slug, status, price and params","description":"The single source of truth for what is callable and what it costs. `paused` tools are listed but return 404 tool_paused.","responses":{"200":{"description":"Tool catalog (slug, path, status, price, output, params)"}}}},"/api/status":{"get":{"operationId":"getStatus","summary":"Live health: database, storage, scheduler heartbeat, last hour's job counts","description":"Returns 200 when everything answers and the scheduler has reported in the last 2 minutes, 503 when degraded. Check this before assuming a failed request is your fault.","responses":{"200":{"description":"Healthy — `{ok, checked_at, checks, last_hour}`"},"503":{"description":"Degraded — same body, `ok: false`"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"Remote MCP endpoint (Streamable HTTP, stateless) — JSON-RPC 2.0","description":"Point an MCP host at `POST /mcp`. One tool: `remove_background` (arguments: `image_base64` or `image_url`, plus `background` / `color` / `format`). The result is an MCP image content block.  Stateless: no `Mcp-Session-Id`, no SSE stream (`GET` → 405), no `DELETE`. Same quota as REST — anonymous 10 images/day per IP, optional `Authorization: Bearer sk_free_…` raises it to 30/day.","security":[{},{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request (or batch): initialize / ping / tools/list / tools/call"}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"},"202":{"description":"Notification accepted (no body)"},"405":{"description":"GET/DELETE: this server is stateless"}}}},"/api/presign":{"post":{"operationId":"presign","summary":"Reserve a jobId and get an upload URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignRequest"}}}},"responses":{"200":{"description":"Upload URL issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresignResponse"}}}},"400":{"description":"Unsupported type or size over 10MB"},"403":{"description":"Bot check failed (only when Turnstile is enabled)"},"409":{"description":"Mask presign before the photo was uploaded"}}}},"/api/jobs":{"post":{"operationId":"createJob","summary":"Queue a job for an already uploaded image","description":"Validates params before touching the database. Unknown capability -> 400. Job not found -> 404. Already submitted -> 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JobRequest_image_enhance"},{"$ref":"#/components/schemas/JobRequest_image_colorize"},{"$ref":"#/components/schemas/JobRequest_image_cutout"},{"$ref":"#/components/schemas/JobRequest_image_white_bg"},{"$ref":"#/components/schemas/JobRequest_image_erase"},{"$ref":"#/components/schemas/JobRequest_image_upscale"},{"$ref":"#/components/schemas/JobRequest_image_extend"},{"$ref":"#/components/schemas/JobRequest_image_text_scan"},{"$ref":"#/components/schemas/JobRequest_image_generate"}]}}}},"responses":{"200":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"description":"Invalid capability, params, or missing mask","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Job not found — upload first"},"409":{"description":"Job already submitted"}}}},"/api/jobs/{jobId}":{"get":{"operationId":"getJob","summary":"Poll job status","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"400":{"description":"Malformed jobId"},"404":{"description":"Job not found"}}}},"/api/remove-background":{"post":{"operationId":"run_remove_background","summary":"Remove background — Cut out the subject onto transparency, white, or any solid color","description":"Price: $0.01 per call (USD).\nSend the image bytes as the request body — either raw (`Content-Type: image/jpeg|png|webp`)\nor as `multipart/form-data` with an `image` field. Tool params go in `params` (a JSON object).\n\n`wait` = how many seconds the request blocks (1–25, default 20). If the job is still running you get\n`202` with `job_id` and `status_url`; the job is not lost. `format=json` returns JSON with a signed\n`result_url` instead of the image bytes.","security":[{"bearerKey":[]}],"parameters":[{"name":"params","in":"query","schema":{"type":"string"},"description":"JSON object of tool params (URL-encoded)","examples":{"white":{"value":"{\"background\":\"white\"}"},"solid":{"value":"{\"background\":\"color\",\"color\":\"#f2f2f2\"}"},"jpeg":{"value":"{\"background\":\"white\",\"format\":\"jpeg\"}"}}},{"name":"wait","in":"query","schema":{"type":"number","minimum":1,"maximum":25,"default":20},"description":"Seconds to block waiting for the result"},{"name":"format","in":"query","schema":{"type":"string","enum":["json"]},"description":"Set to json for a structured response instead of image bytes"},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"},"description":"Bearer sk_free_… (optional: anonymous gets 10/day per IP)"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/RunForm"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Done — image bytes by default, RunResult with Accept: application/json","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/RunResult"}}}},"202":{"description":"Still running — poll status_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunPending"}}}},"400":{"description":"`bad_param` (invalid tool params; `details` names the field), `bad_json`, `missing_image`, `bad_request` (unreadable body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized` — missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`unknown_tool` (no such slug — see GET /api/tools) or `tool_paused` (registered, not open yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"`job_expired` — the result was deleted 24 hours after it was produced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`image_too_large` — over 10 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"`unsupported_media_type` — not JPEG/PNG/WebP (sniffed from the bytes, not the header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`quota_exhausted` — today's free allowance is gone. Body carries `limit`, `used`, `kind` and links to /signup, /login, /account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal_error` — the job could not be created; the quota unit was refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"`processing_failed` or `storage_error` — the quota unit was refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`capacity_full` (shared anonymous channel full today) or `service_unavailable` — retry with backoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_free_xxx","description":"Free key from https://photosweat.shop/signup (or POST /api/auth/keys); optional for anonymous use"}},"schemas":{"JobRequest_image_enhance":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.enhance","description":"Portrait enhance — Restore blurry faces and balance surrounding sharpness without recoloring (about 12s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"balance":{"description":"Off = faces only","default":true,"type":"boolean"}}}}},"JobRequest_image_colorize":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.colorize","description":"Colorize — Colorize B&W photos; keeps existing colors on color photos (about 20s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{}}}},"JobRequest_image_cutout":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.cutout","description":"Remove background — Cut out the subject onto transparency, white, or any solid color (about 10s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"background":{"description":"Transparent, white, or a custom color","default":"transparent","type":"string","enum":["transparent","white","color"]},"color":{"description":"Only used when background=color","default":"#ffffff","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"format":{"description":"JPEG is much smaller for opaque backgrounds; transparency requires PNG","default":"png","type":"string","enum":["png","jpeg"]}}}}},"JobRequest_image_white_bg":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.white-bg","description":"White background — Cutout, white fill, and marketplace-safe framing (about 10s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"background":{"description":"Background","default":"white","type":"string","enum":["white","transparent","color"]},"color":{"description":"Only when background=color","default":"#ffffff","type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"fillRatio":{"description":"Subject area share; most marketplaces require >=85","default":85,"type":"number","minimum":50,"maximum":100},"longEdge":{"description":"0 = derive from fill ratio","default":1600,"type":"integer","minimum":0,"maximum":4096},"verifyText":{"description":"Compare text before/after cutout; never blocks output","default":true,"type":"boolean"}}}}},"JobRequest_image_erase":{"type":"object","required":["jobId","capability","mask"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.erase","description":"Erase — Remove watermarks, stamps, stains; texture only, no generation (about 8s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{}},"mask":{"type":"boolean","const":true,"description":"Required for this capability. Upload the mask first: POST /api/presign with mask:true, then PUT the PNG to the returned uploadUrl."}}},"JobRequest_image_upscale":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.upscale","description":"Upscale — Real-ESRGAN upscale; prefer 2x on text-heavy images (about 16s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"scale":{"description":"Use 2x for packaging text","default":"4","type":"string","enum":["2","4"]},"engine":{"description":"Pick x4plus for text-heavy images: less halo and stroke adhesion","default":"ultrasharp","type":"string","enum":["ultrasharp","x4plus"]},"verifyText":{"description":"OCR diff before/after upscale; reports missing or changed text (~1-2s)","default":true,"type":"boolean"}}}}},"JobRequest_image_extend":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.extend","description":"Extend — LaMa outpainting; extends texture, does not invent objects (about 18s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"percent":{"description":"Extend per side (%)","default":20,"type":"number","minimum":1,"maximum":25}}}}},"JobRequest_image_text_scan":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.text-scan","description":"Sensitive text scan — Detect all text in a product image and flag banned ad-law words; returns annotated image + report (about 8s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"platform":{"description":"Check against that platform's rule pack; findings only, no approval guarantee","default":"all","type":"string","enum":["all","amazon","tmall","douyin","cn-ad-law"]}}}}},"JobRequest_image_generate":{"type":"object","required":["jobId","capability"],"properties":{"jobId":{"type":"string","format":"uuid","description":"jobId returned by POST /api/presign"},"capability":{"type":"string","const":"image.generate","description":"Text to image — Describe what you want and FLUX generates the image; 6 styles, 5 aspect ratios (4090 lane, no input image) (about 15s)"},"params":{"type":"object","description":"Every field may be omitted; omitted fields take their default. Unknown fields are ignored.","properties":{"prompt":{"description":"Describe the scene; English prompts tend to work best","default":"","type":"string","minLength":1},"style":{"description":"One model; styles are prompt prefixes","default":"none","type":"string","enum":["none","photo","anime","3d","watercolor","flat"]},"aspect":{"description":"Output ratio","default":"1:1","type":"string","enum":["1:1","3:4","4:3","16:9","9:16"]},"seed":{"description":"Same seed reproduces the same image","default":0,"type":"integer"}}}}},"RunForm":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"JPEG / PNG / WebP, up to 10MB"},"mask":{"type":"string","format":"binary","description":"PNG, white = processed area; required by image.erase"},"capability":{"type":"string","default":"image.cutout"},"params":{"type":"string","description":"JSON object as a string"}}},"RunResult":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"done"},"capability":{"type":"string"},"params":{"type":"object","description":"Normalized params after defaults were applied"},"result_url":{"type":"string","description":"Signed URL, valid for one hour"},"original_url":{"type":["string","null"],"description":"Signed URL of the input, valid for one hour"}}},"RunPending":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"queued"},"capability":{"type":"string"},"params":{"type":"object"},"status_url":{"type":"string","description":"GET this until status is done/failed"},"retry_after":{"type":"integer","description":"Seconds"}}},"Quota":{"type":"object","properties":{"kind":{"type":"string","enum":["key","anon"]},"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"account":{"type":["string","null"],"description":"Account id, or null for anonymous / legacy keys"},"credits":{"type":"integer","description":"Prepaid images left ($10 = 1000), spent after the daily allowance"},"rate_limit_per_min":{"type":"integer","description":"Per-minute request ceiling; 0 = disabled on this deployment"}}},"NewKey":{"type":"object","properties":{"key":{"type":"string","description":"sk_free_… — shown once, only its SHA-256 is stored"},"dailyLimit":{"type":"integer"}}},"PresignRequest":{"type":"object","required":["size","type"],"properties":{"size":{"type":"int","minimum":1,"maximum":10485760,"description":"Bytes"},"type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"turnstileToken":{"type":"string","description":"Only required when the site enables Turnstile"},"mask":{"type":"boolean","description":"Set true to request the mask upload URL instead"},"jobId":{"type":"string","format":"uuid","description":"Required when mask is true"}}},"PresignResponse":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"uploadUrl":{"type":"string","description":"PUT the bytes here; expires in maxAge seconds"},"maskKey":{"type":"string","description":"Present only for mask presigns"},"maxAge":{"type":"integer"}}},"JobAccepted":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","processing"]},"capability":{"type":["string","null"]},"params":{"type":["object","null"],"description":"Normalized params after defaults were applied"}}},"JobStatus":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","queued","processing","done","error","expired"]},"error":{"type":["string","null"]},"resultUrl":{"type":["string","null"],"description":"Signed URL, valid for one hour"},"downloadUrl":{"type":["string","null"]},"originalUrl":{"type":["string","null"]},"shareUrl":{"type":["string","null"],"description":"Stable page link, /r/{id}"},"options":{"type":["object","null"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"One English sentence for a human. Wording may change — never branch on this field."},"code":{"type":"string","description":"Stable machine contract: same situation, same code, forever. Branch on this.","enum":["bad_request","bad_json","bad_param","missing_image","image_too_large","unsupported_media_type","missing_mask","bad_mask","no_input","unknown_tool","tool_paused","unauthorized","rate_limited","quota_exhausted","capacity_full","job_not_found","job_expired","processing_failed","storage_error","internal_error","service_unavailable"]},"hint":{"type":"string","description":"Optional next step (register, retry, read /api/tools)."},"capability":{"type":"string"},"tool":{"type":"string"},"details":{"type":"array","items":{"type":"string"},"description":"Per-field validation failures (`field: what is wrong`). Only with `bad_param`."},"job_id":{"type":"string"},"limit":{"type":"integer","description":"Daily allowance that ran out (`quota_exhausted`)."},"used":{"type":"integer"},"kind":{"type":"string","enum":["anon","free","pro","web"]}}},"Capabilities":{"type":"object","properties":{"version":{"type":"integer"},"tier":{"type":"string","enum":["free"]},"capabilities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"object","properties":{"zh":{"type":"string"},"en":{"type":"string"}}},"summary":{"type":"object","properties":{"zh":{"type":"string"},"en":{"type":"string"}}},"output":{"type":"string"},"costSeconds":{"type":"number"},"requiresMask":{"type":"boolean"},"params":{"type":"object"}}}}}}}}}